---
title: "The session's standing goal, or null [read]"
method: GET
path: "/sessions/{id}/goal"
---

# The session's standing goal, or null \[read\]

`GET /sessions/{id}/goal`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/sessions/{id}/goal`
- Auth: HTTP bearer

A goal is an objective the session works toward on its own: after each turn settles, the platform grades the work against the goal's criteria and either takes another turn or stops. At most one goal per session.

## Path parameters

- `id` string, required

## Response `200`

OK

- object
  - `goal` Goal, required
    - `id` string, required: goal_…
    - `session` string, required: sess_…
    - `objective` string, required
    - `criteria` GoalCriterion[], required
      - `id` string, required: Stable within the goal, e.g. c1
      - `text` string, required
      - `command` string: Present when a shell command decides this criterion: it runs in the session's workspace after each iteration, and exit 0 means met. The grader cannot overturn it.
    - `criteria_source` 'user' | 'derived', required: Whether the caller supplied the criteria or the platform derived them from the objective
    - `status` 'active' | 'paused' | 'completed' | 'stopped', required
    - `stop_reason` 'failed' | 'max_iterations' | 'spend_budget' | 'token_budget' | 'time_budget' | 'no_progress' | 'cleared' | 'session_ended' | 'null', nullable, required: Why a stopped goal stopped; null in every other status
    - `iteration` integer, required: Self-started turns taken so far
    - `max_iterations` integer, required
    - `max_spend` MonetaryAmount, required: A US-dollar amount. `amount` is whole US cents as an integer decimal string — "125" is $1.25 — rounded half-up to the cent.
      - `amount` string, required: Whole US cents
      - `currency` 'USD', required
      - `unit` 'cents': The unit of `amount`; present on every amount the API returns
      - `amount_usd` string: The exact amount in US dollars, up to six decimals — "0.0038" for spend that rounds to 0 cents. Returned, never accepted.
    - `consumed_spend` MonetaryAmount, required: A US-dollar amount. `amount` is whole US cents as an integer decimal string — "125" is $1.25 — rounded half-up to the cent.
      - `amount` string, required: Whole US cents
      - `currency` 'USD', required
      - `unit` 'cents': The unit of `amount`; present on every amount the API returns
      - `amount_usd` string: The exact amount in US dollars, up to six decimals — "0.0038" for spend that rounds to 0 cents. Returned, never accepted.
    - `max_tokens` integer, nullable, required: Token ceiling for this goal; null = none
    - `consumed_tokens` integer, required: Uncached input plus output tokens over the session's metered model calls since the goal started, grading included. Calls on the session's own model subscription are not metered and not counted.
    - `deadline_at` string, date-time, nullable, required
    - `last_evaluation` GoalEvaluation, required: The grader's read of the most recent iteration.
      - `result` 'satisfied' | 'needs_revision' | 'failed', required
      - `explanation` string, required
      - `criteria` object[], required
        - `id` string, required
        - `met` boolean, required
        - `reason` string, required
        - `judged_by` 'grader' | 'command': What decided this criterion on this iteration
      - `iteration` integer, required
      - `at` string, date-time, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `completed_at` string, date-time, nullable, required

## Other responses

- `default`: Error — { error: { code, message } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 2 breaking, 2 warning, 3 info
  - added `#/components/schemas/MonetaryAmount` to the `goal/oneOf[#/components/schemas/Goal]/max_spend` response property `oneOf` list for the response status `200`
  - the `goal/oneOf[#/components/schemas/Goal]/consumed_spend` response's property type changed from `object` to no type for status `200`
  - removed the optional property `goal/oneOf[#/components/schemas/Goal]/consumed_spend/amount` from the response with the `200` status
  - removed the optional property `goal/oneOf[#/components/schemas/Goal]/consumed_spend/currency` from the response with the `200` status
  - …3 more

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/sessions/:id/goal/get.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/8280a065ef6a?raw)