---
title: "Predict within an existing session"
method: POST
path: "/v1/sessions/{session_id}/predict"
tags: ["sessions"]
---

# Predict within an existing session

`POST /v1/sessions/{session_id}/predict`

Managed-inference base: 4 credits per stateful prediction. The same trajectory-image, HD current/trajectory image, v1-engine, and combined system_prompt + trimmed instructions (>500 characters) surcharges as POST /v1/predict can apply; the stateful trajectory surcharge uses the provider-visible post-compaction image count. A session created with BYOK inherits that provider/key for every predict and debits zero Coasty platform credits while returning actual provider tokens. Session predict is a direct CUA primitive and remains provider-direct under a test Coasty key only when session create supplied the explicit per-request X-LLM-Api-Key; the provider account can then be billed. Test auth never resolves a stored live provider key for the session. Read effective deployed pricing from GET /v1/models under pricing.

## Headers

- `Idempotency-Key` string

## Request body

- SessionPredictRequest
  - `screenshot` union, required — One static PNG/JPEG screenshot as raw base64 or an exact data:image/png;base64 / data:image/jpeg;base64 URI. Animated and multi-frame images are rejected. This per-image limit does not multiply the ordinary 15 MiB aggregate JSON request-body cap.
    - string
    - string
    - string
  - `instruction` string, required
  - `include_reasoning` boolean
  - `include_raw_code` boolean

## Response `200`

Predicted actions for the next step.

- SessionPredictResponse
  - `request_id` string, required
  - `session_id` string, required
  - `step` integer, required
  - `actions` ActionResponse[], required — unresolved $ref
  - `raw_code` string[]
  - `reasoning` string
  - `status` 'continue' | 'done' | 'fail', required — Authoritative model loop-control claim for this session step. done may describe the observed state or the proposed step outcome and may coexist with mutating actions; it is not proof of persistence and does not close the session. Execute only admitted actions, capture a fresh post-action screenshot, verify application state, then DELETE or reset the session at the intended flow boundary.
  - `cua_version` string, nullable — Echo: the CUA engine version that actually served this step (e.g. "v5").
  - `usage` UsageInfo, required
    - `input_tokens` integer
    - `output_tokens` integer
    - `credits_charged` integer
    - `cost_cents` integer — USD-cent amount; the same numeric value as credits_charged (divide by 100 for USD).
    - `breakdown` object[], nullable — Self-auditable per-call cost breakdown; line credits sum to credits_charged. null on free/test/no-charge calls and /v1/parse.
      - `item` 'base' | 'trajectory' | 'hd_images' | 'engine' | 'custom_prompt', required
      - `credits` integer, required
      - `count` integer, nullable — Optional multiplier (e.g. number of HD screenshots billed); omitted where it adds nothing.
    - `billed` boolean — true on a real Coasty wallet debit; false on BYOK, test keys (sk-coasty-test-*), and idempotent replays (all return credits_charged: 0).
    - `llm_provider` 'managed' | 'anthropic' | 'openai' — Effective inference provider. Non-managed values identify provider-direct BYOK execution.
    - `llm_model` string, nullable — Effective BYOK model id; null for managed inference.
    - `llm_key_fingerprint` string, nullable — Non-secret SHA-256 prefix identifying the BYOK key; never the key itself.
    - `llm_key_source` 'header' | 'stored', nullable — Where the effective BYOK key came from; null for managed inference.
    - `platform_cost_exempt` boolean — true for BYOK. Coasty credits/cost are zero. Provider billing occurs only for provider-direct execution. Managed-mode test Task, Workflow, and schedule sandbox execution makes no provider call; test-auth BYOK intent on those async endpoints is rejected before execution.

## Other responses

- `400` — Invalid request body or parameters.
- `401` — Missing, invalid, or revoked API key. Pass `X-API-Key: sk-coasty-live-...` (or test).
- `402` — Insufficient balance for this operation. Direct metered API calls and managed-machine runtime use the prepaid Developer API wallet; scheduled execution is the documented consumer subscription-credit exception. Follow the operation's billing fields and top up the matching balance in the dashboard.
- `403` — API key lacks the required scope or tier-feature is unavailable on the caller's plan.
- `404` — Resource not found in this key's namespace.
- `409` — The resource state conflicts with this operation.
- `413` — The request body exceeds the endpoint limit.
- `422` — The JSON shape is valid but one or more values violate the endpoint contract.
- `429` — Rate or concurrency limit exceeded.
- `500` — Unexpected server error. Retry with exponential backoff.
- `502` — An upstream dependency returned an invalid response.
- `503` — A required service is temporarily unavailable.
- `504` — An upstream dependency timed out.

---

[API](https://skmtc.net/coasty/apis/coasty-public-api.md) · [All operations](https://skmtc.net/coasty/apis/coasty-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/coasty/coasty-public-api/revisions/f50d93b0d8a1/schema)