# Responses (/api-v2/responses)



The native `/v2/responses` surface pins session state and a QoS request directly in the request body, rather than squeezing them through compatibility headers as `/v1` does. The response carries the chosen execution profile and the formal QoS outcome inline. Response ids are prefixed `rsp_`. See [QoS](/concepts/qos).

All requests require a bearer API key. Creating a response runs inference, so the project must have a positive prepaid credit balance and be under its budget. See [authentication](/api-reference/authentication) and [billing and budgets](/guides/billing-budgets).

## Create a response [#create-a-response]

`POST /v2/responses`

<ParamField body="model" type="string">
  The model alias or concrete target to run, e.g. `code.fast`. Resolved through an immutable [alias release](/api-v2/model-aliases).
</ParamField>

<ParamField body="input" type="string">
  The input text. Must not be empty.
</ParamField>

<ParamField body="session_id" type="string">
  Optional `ses_...` to associate the response with a session. Must exist in this project.
</ParamField>

<ParamField body="branch_id" type="string">
  Optional `br_...` branch within the session. Must resolve through a session this project owns.
</ParamField>

<ParamField body="qos" type="object">
  Optional explicit QoS request. Defaults to the `standard` class with no hard targets and compatible fallback allowed.

  <Expandable title="qos">
    <ParamField body="class" type="string">
      One of `interactive`, `standard`, `background`, `batch`.
    </ParamField>

    <ParamField body="target_ttft_ms" type="integer">
      Time-to-first-token target. The outcome reports `target_met` against it.
    </ParamField>

    <ParamField body="deadline_ms" type="integer">
      Hard deadline. If the provider does not respond within this window the request aborts with `deadline_exceeded` (504) and is never charged.
    </ParamField>

    <ParamField body="priority" type="integer">
      Scheduling priority hint, 0-255.
    </ParamField>

    <ParamField body="degrade_policy" type="string">
      One of `forbid`, `allow_compatible_fallback`.
    </ParamField>
  </Expandable>
</ParamField>

```bash
curl https://api.zumik.ai/v2/responses \
  -H "Authorization: Bearer $ZUMIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "code.fast",
    "input": "Summarize the diff in three bullets.",
    "session_id": "ses_01jy7n7w2z9pcu7a5q2gh8askm",
    "branch_id": "br_01jy7n7w30ardv8b6r3jk9btln",
    "qos": { "class": "interactive", "target_ttft_ms": 500, "deadline_ms": 8000, "degrade_policy": "allow_compatible_fallback" }
  }'
```

```python
from zumik import Zumik

zk = Zumik()
resp = zk.responses.create(
    model="code.fast",
    input="Summarize the diff in three bullets.",
    session_id=session.id,
    branch_id=session.default_branch_id,
    qos={"class": "interactive", "target_ttft_ms": 500, "deadline_ms": 8000},
)
```

```json
{
  "id": "rsp_01jy7ndf89g0h1j2k3l4m5n6op",
  "object": "response",
  "session_id": "ses_01jy7n7w2z9pcu7a5q2gh8askm",
  "branch_id": "br_01jy7n7w30ardv8b6r3jk9btln",
  "status": "completed",
  "model": "code.fast",
  "execution_profile": "managed_provider",
  "output_text": "- Adds a CAS guard to branch append\n- Cleans up the dead retry shim\n- Bumps the test fixtures",
  "qos_outcome": {
    "admission": "admitted",
    "completion": "completed",
    "target_met": true,
    "ttft_ms": 312,
    "latency_ms": 1840,
    "deadline_met": true,
    "degraded": false,
    "fallback_used": false,
    "reason_code": null
  }
}
```

<ResponseField name="id" type="string">
  Opaque response id, prefixed `rsp_`.
</ResponseField>

<ResponseField name="object" type="string">
  Always `response`.
</ResponseField>

<ResponseField name="session_id" type="string">
  The associated session, or `null`.
</ResponseField>

<ResponseField name="branch_id" type="string">
  The associated branch, or `null`.
</ResponseField>

<ResponseField name="status" type="string">
  `completed` on success; `cancelled` after a cancel.
</ResponseField>

<ResponseField name="model" type="string">
  The requested model, echoed back.
</ResponseField>

<ResponseField name="execution_profile" type="string">
  Which profile served the request: `managed_provider`, `byok`, or `subscription`.
</ResponseField>

<ResponseField name="output_text" type="string">
  The generated text.
</ResponseField>

<ResponseField name="qos_outcome" type="object">
  The formal QoS outcome.

  <Expandable title="qos_outcome">
    <ResponseField name="admission" type="string">
      One of `admitted`, `queued`, `rejected`, `expired_before_start`.
    </ResponseField>

    <ResponseField name="completion" type="string">
      One of `completed`, `failed`, `cancelled`, `expired_during_execution`.
    </ResponseField>

    <ResponseField name="target_met" type="boolean">
      Whether `target_ttft_ms` was met, or `null` when no target was set.
    </ResponseField>

    <ResponseField name="ttft_ms" type="integer">
      Observed time to first token.
    </ResponseField>

    <ResponseField name="latency_ms" type="integer">
      Observed total latency.
    </ResponseField>

    <ResponseField name="deadline_met" type="boolean">
      Whether `deadline_ms` was met, or `null` when none was set.
    </ResponseField>

    <ResponseField name="degraded" type="boolean">
      Whether the request was served in a degraded mode.
    </ResponseField>

    <ResponseField name="fallback_used" type="boolean">
      Whether a fallback profile served the request.
    </ResponseField>

    <ResponseField name="reason_code" type="string">
      A stable reason code when a target was missed, otherwise `null`. One of `queue_saturation`, `provider_rate_limit`, `provider_timeout`, `region_unavailable`, `alias_no_compatible_target`, `cache_miss`, `cache_transfer_slower_than_recompute`, `fallback_profile_used`, `customer_deadline_too_short`.
    </ResponseField>
  </Expandable>
</ResponseField>

## Retrieve a response [#retrieve-a-response]

`GET /v2/responses/{response_id}`

<ParamField path="response_id" type="string">
  The `rsp_...` id to fetch.
</ParamField>

```bash
curl https://api.zumik.ai/v2/responses/rsp_01jy7ndf89g0h1j2k3l4m5n6op \
  -H "Authorization: Bearer $ZUMIK_API_KEY"
```

Returns the stored response object.

## Cancel a response [#cancel-a-response]

`POST /v2/responses/{response_id}/cancel`

Marks a stored response `cancelled`. Returns the updated object.

<ParamField path="response_id" type="string">
  The `rsp_...` id to cancel.
</ParamField>

```bash
curl -X POST https://api.zumik.ai/v2/responses/rsp_01jy7ndf89g0h1j2k3l4m5n6op/cancel \
  -H "Authorization: Bearer $ZUMIK_API_KEY"
```

## Errors [#errors]

| Status | Code                                     | When                                                                                           |
| ------ | ---------------------------------------- | ---------------------------------------------------------------------------------------------- |
| 400    | `invalid_request_error`                  | `input` is empty, or `session_id` / `branch_id` does not exist in this project.                |
| 401    | `invalid_api_key`                        | Missing or invalid API key.                                                                    |
| 402    | `credits_required`                       | The prepaid credit balance is empty.                                                           |
| 403    | `region_not_allowed`                     | The resolved region is forbidden by this project's [regional policy](/api-v2/regional-policy). |
| 404    | `invalid_request_error`                  | The response does not exist in this project.                                                   |
| 429    | `quota_exceeded` / `rate_limit_exceeded` | Budget reached, or per-key rate limit exceeded.                                                |
| 504    | `deadline_exceeded`                      | The QoS `deadline_ms` elapsed before the provider responded. The request is not charged.       |

See the full table on [errors](/api-reference/errors).