---
title: "Report a task outcome"
method: POST
path: "/v1/outcomes"
---

# Report a task outcome

`POST /v1/outcomes`

## Request

- Base URL: `https://api.agentlab.cresclab.com`
- URL: `https://api.agentlab.cresclab.com/v1/outcomes`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/cresclab/apis/agent-lab-ai-gateway/docs/v1/outcomes/post.ts> (a function with typed inputs; its response is checked against the schema)

Says, after the answer, whether a request or the agent run it belongs to succeeded. Name the request by the X-Request-Id (or chatcmpl_ id) its answer carried, or the run by the trace id its requests arrived with in traceparent; exactly one. Any key of the workspace may report, within 31 days of the request (for a run, its most recent request). A later report replaces the earlier one; a request's own outcome wins over its run's. Usage counts cost per successful task only from reported outcomes.

## Request body

- union
  - object
    - `request_id` string, required: The X-Request-Id, or the chatcmpl_ id, of the request's answer.
    - `trace_id` string: The trace id of the traceparent the run's requests arrived with.
    - `outcome` 'success' | 'failure', required
  - object
    - `request_id` string: The X-Request-Id, or the chatcmpl_ id, of the request's answer.
    - `trace_id` string, required: The trace id of the traceparent the run's requests arrived with.
    - `outcome` 'success' | 'failure', required

## Response `200`

What was recorded and how many requests it applies to.

- object
  - `subject` object
    - `kind` 'request' | 'trace'
    - `id` string
  - `outcome` 'success' | 'failure'
  - `requests` integer

## Other responses

- `400`: invalid_outcome: not exactly one subject, an id of the wrong shape, or an outcome other than success or failure.
- `401`: Missing or not accepted key.
- `403`: Not allowed for this key or workspace.
- `404`: outcome_subject_not_found: no such request or run in this key's workspace; the same answer for another workspace's id.
- `409`: outcome_window_closed: the request, or the run's most recent request, was prepared more than 31 days ago.
- `429`: Too many failed key attempts from this address.
- `503`: Gateway unavailable.

---

[API](https://skmtc.dev/cresclab/apis/agent-lab-ai-gateway.md) - [All operations](https://skmtc.dev/cresclab/apis/agent-lab-ai-gateway/llms.txt) - [OpenAPI document](https://skmtc.dev/cresclab/apis/agent-lab-ai-gateway/revisions/5dc08011cbe9?raw)