> ## Documentation Index > Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Define what done looks like for a session > Defines what done looks like for an existing session and returns the stored outcome. Outcomes chain rather than run concurrently: the request is rejected while the session still has a non-terminal outcome, so define the next one only after the previous is graded. ## OpenAPI ````yaml /managed-agents/openapi.yaml post /managed-agents/v1/sessions/{session_id}/outcomes openapi: 3.1.0 info: title: Managed Agents API version: 0.14.0 description: >- The Recursion Managed Agents REST API. Authenticate with a Recursion API key as a bearer token. An organization-scoped key acts in its own organization and needs nothing else; a tenant-scoped key must also send `x-organization-id` with an organization id or `default`. Field names follow each operation's published schema. servers: - url: https://api.recursion.labelbox.com security: - bearerAuth: [] paths: /managed-agents/v1/sessions/{session_id}/outcomes: post: tags: - Sessions summary: Define what done looks like for a session description: >- Defines what done looks like for an existing session and returns the stored outcome. Outcomes chain rather than run concurrently: the request is rejected while the session still has a non-terminal outcome, so define the next one only after the previous is graded. operationId: managedAgentsDefineSessionOutcome parameters: - description: Session id (UUID) as returned by startSession or listSessions. in: path name: session_id required: true schema: description: Session id (UUID) as returned by startSession or listSessions. format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsDefineOutcomeRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsOutcome' description: >- A session's definition of done: the task to achieve plus a rubric a grader scores the work against, tracked through its own grading lifecycle. Defined when the session starts, and read back to see whether the work was accepted. '400': description: The request was rejected by schema or semantic validation. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' discriminator: propertyName: code mapping: invalid_json: $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' invalid_request: $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' '401': description: The caller is unauthenticated. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnauthorized' '403': description: The caller lacks a required permission or capability. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' '404': description: No such resource is reachable for this caller. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorNotFound' '409': description: >- The request conflicts with the resource state, or with an in-flight idempotent replay. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorConflict' '413': description: The request exceeds a size or transaction budget. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorPayloadTooLarge' '415': description: The request body uses a media type this operation does not accept. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnsupportedMediaType' '429': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string description: A rate limit is exhausted. Honor `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorRateLimitExceeded' '500': description: An unexpected server-side failure. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError' - $ref: >- #/components/schemas/ManagedAgentsApiErrorInvariantViolation discriminator: propertyName: code mapping: internal_error: $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError' invariant_violation: $ref: >- #/components/schemas/ManagedAgentsApiErrorInvariantViolation '502': description: The service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorBadGateway' '503': description: >- A dependency is unavailable. Consult details.retryable and Retry-After when present before retrying. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorFileStorageUnconfigured - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable discriminator: propertyName: code mapping: file_storage_unconfigured: $ref: >- #/components/schemas/ManagedAgentsApiErrorFileStorageUnconfigured managed_agents_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable service_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable '504': description: The service did not respond before the timeout. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorGatewayTimeout' components: schemas: ManagedAgentsDefineOutcomeRequest: description: >- A definition of done for a session -- the task plus the rubric it is graded against. Accepted both when starting a session and when adding an outcome to a running one. Exactly one of rubric and rubric_ref is required. examples: - description: Export the product catalog to /out/catalog.csv rubric: |- - /out/catalog.csv exists - The CSV has a header row with sku, name, and price columns - Every price value is a number oneOf: - required: - rubric - required: - rubric_ref properties: description: description: >- The objective the agent works toward, and the statement of it the grader is given. It opens the session when the start request carries no message. minLength: 1 type: string grader_model_ref_id: description: Model reference for the grader. Defaults to the session's model. type: string max_iterations: default: 0 description: >- Ceiling on grader passes before the outcome ends as max_iterations_reached. Omit it, or send 0, to revise until the grader is satisfied, which is the default. Set a number only to cap a rubric you are not sure can be met. format: int64 minimum: 0 type: integer rubric: description: >- Markdown the grader scores the work against. Criteria must be independently checkable: 'the CSV has a numeric price column' can be verified, 'the data looks good' cannot. Send this or rubric_ref. minLength: 1 type: string rubric_ref: $ref: '#/components/schemas/ManagedAgentsOutcomeRubricRef' description: >- The rubric as a file instead of inline markdown: the file's text is read once, when the outcome is defined, and recorded as the rubric. Exactly one of rubric and rubric_ref is required. required: - description type: object example: description: Export the product catalog to /out/catalog.csv rubric: |- - /out/catalog.csv exists - The CSV has a header row with sku, name, and price columns - Every price value is a number ManagedAgentsOutcome: description: >- A session's definition of done: the task to achieve plus a rubric a grader scores the work against, tracked through its own grading lifecycle. Defined when the session starts, and read back to see whether the work was accepted. properties: agent_id: description: >- Agent this outcome belongs to (UUID), copied from the session that defined it. type: string created_at: description: RFC 3339 timestamp of when this record was created. Server-assigned. format: date-time type: string defined_by_event_id: description: Event in the session's log that defined this outcome (UUID). type: string description: description: >- Objective the agent works toward, in prose, and the statement of it quoted to the grader. Opens the session when the start request carries no message. type: string ended_at: description: >- RFC 3339 timestamp of when grading reached a terminal result. Absent while the outcome is still open. format: date-time type: string evaluations: description: >- Grader passes in order, newest last. Returned only by reads that ask for evaluations, and empty until a grader has run. items: $ref: '#/components/schemas/ManagedAgentsOutcomeEvaluation' type: array grader_model_ref_id: description: >- Model reference the grader runs on (UUID), letting grading use a different model than the agent doing the work. Defaults to the session's model. type: string max_iterations: description: >- Ceiling on grader passes before the outcome ends as max_iterations_reached. Zero means unbounded, which is the default: the loop runs until the grader is satisfied. format: int64 type: integer organization_id: description: >- Organization that owns this record. Resolved from the API key; never accepted from the caller. type: string outcome_id: description: Identifier for this outcome (UUID). Server-assigned. type: string rubric: description: >- Markdown rubric the grader scores the work against. Write independently checkable criteria; vague criteria produce noisy revision loops. type: string rubric_ref: description: >- Where the rubric text came from when it was not sent inline: file: for a rubric read from a file when the outcome was defined. rubric always carries the text; later changes to the file do not move the bar. type: string rubric_sha256: description: >- Lowercase SHA-256 digest of the uploaded file the rubric was read from, for matching it to the file. Not a digest of rubric: the recorded text is the file's minus a byte-order mark and with line endings normalized. type: string session_id: description: Session this outcome belongs to (UUID). type: string status: description: >- Where the outcome is in its grading lifecycle: pending (no grader has looked at it), running (the agent is working toward it), evaluating (a grader pass is in flight), or terminal (grading finished; read terminal_result). enum: - pending - running - evaluating - terminal type: string terminal_result: description: >- Final verdict, set only once status is terminal: satisfied, max_iterations_reached, failed, or interrupted. Empty before then. enum: - satisfied - max_iterations_reached - failed - interrupted type: string updated_at: description: >- RFC 3339 timestamp of the last change to this record. Server-assigned. format: date-time type: string required: - organization_id - session_id - outcome_id - description - rubric - max_iterations - status - created_at - updated_at type: object example: agent_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d created_at: '2026-02-18T09:30:00.000Z' defined_by_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d description: example ended_at: '2026-02-18T09:30:00.000Z' evaluations: - agent_version_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d cache_read_tokens: 1 cache_write_tokens: 1 cost_micros: 1 criteria: - criterion_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d criterion_text: example evidence_event_ids: - example rationale: example section: example verdict: example weight: 1.5 end_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d ended_at: '2026-02-18T09:30:00.000Z' explanation: example grader_model_ref_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d grader_thread_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d input_tokens: 1 iteration: 1 outcome_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d output_tokens: 1 result: satisfied start_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d started_at: '2026-02-18T09:30:00.000Z' grader_model_ref_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d max_iterations: 1 organization_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d outcome_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d rubric: example rubric_ref: example rubric_sha256: example session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d status: pending terminal_result: satisfied updated_at: '2026-02-18T09:30:00.000Z' ManagedAgentsApiErrorInvalidJson: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_json message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInvalidRequest: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_request message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnauthorized: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unauthorized message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorForbidden: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - forbidden message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorNotFound: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - not_found message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorConflict: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - conflict message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorPayloadTooLarge: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - payload_too_large message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnsupportedMediaType: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unsupported_media_type message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorRateLimitExceeded: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - rate_limit_exceeded message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInternalError: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - internal_error message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInvariantViolation: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invariant_violation message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorBadGateway: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - bad_gateway message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorFileStorageUnconfigured: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - file_storage_unconfigured message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorManagedAgentsUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - managed_agents_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorServiceUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - service_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorGatewayTimeout: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - gateway_timeout message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsOutcomeRubricRef: description: A file whose text is an outcome's rubric. properties: file_id: description: >- A file in the caller's organization holding the rubric: text or YAML, at most 256 KiB, uploaded through POST /v1/files. Its text is echoed back as the outcome's rubric. An unknown, expired, or out-of-scope file answers 404; a file that is not text, is oversized, is not UTF-8, or holds no criterion answers 400. format: uuid minLength: 1 type: string type: const: file description: Always file. type: string required: - type - file_id type: object example: file_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d type: file ManagedAgentsOutcomeEvaluation: description: >- One grader pass over the work, with its verdict, its per-criterion scoring, and what it cost. A caller sees these in an outcome's evaluations list, one per revision round. properties: agent_version_id: description: >- Agent version whose work this pass judged (UUID), denormalized onto the criteria so cross-session criterion history is served by an index. type: string cache_read_tokens: description: >- Prompt tokens served from the provider's cache for this unit of work. format: int64 type: integer cache_write_tokens: description: Prompt tokens written to the provider's cache for this unit of work. format: int64 type: integer cost_micros: description: >- Accrued cost in micro-USD (1,000,000 = 1 USD). Integer to avoid float rounding across many small charges. format: int64 type: integer criteria: description: >- Per-criterion verdicts this pass produced, in rubric order. Empty when the grader returned only an overall result. items: $ref: '#/components/schemas/ManagedAgentsOutcomeCriterion' type: array end_event_id: description: >- Event on the graded session's own transcript that recorded this pass's verdict. Locates where the pass landed. type: string ended_at: description: >- RFC 3339 timestamp of when this grader pass finished. Absent while the pass is still in flight. format: date-time type: string explanation: description: >- Grader's message to the agent. For needs_revision this is the per-criterion gap list the next turn has to close. type: string grader_model_ref_id: description: Model reference the grader actually ran on for this pass (UUID). type: string grader_thread_id: description: >- Thread the grader ran in (UUID), so its own reasoning can be read back separately from the agent's transcript. type: string input_tokens: description: Prompt tokens billed for this unit of work. format: int64 type: integer iteration: description: >- 0-indexed pass number: 0 is the first evaluation, 1 the re-evaluation after the first revision. format: int64 type: integer outcome_id: description: Outcome this evaluation belongs to (UUID). type: string output_tokens: description: Completion tokens billed for this unit of work. format: int64 type: integer result: description: >- Verdict of this pass. needs_revision is the only non-terminal value and sends the agent back for another turn; the rest end the outcome. enum: - satisfied - needs_revision - max_iterations_reached - failed - interrupted type: string start_event_id: description: >- First event of the grader thread for this pass, which is the packet the harness handed it. Locates where the pass began. type: string started_at: description: RFC 3339 timestamp of when this grader pass began. format: date-time type: string required: - outcome_id - iteration - result type: object example: agent_version_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d cache_read_tokens: 1 cache_write_tokens: 1 cost_micros: 1 criteria: - criterion_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d criterion_text: example evidence_event_ids: - example rationale: example section: example verdict: example weight: 1.5 end_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d ended_at: '2026-02-18T09:30:00.000Z' explanation: example grader_model_ref_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d grader_thread_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d input_tokens: 1 iteration: 1 outcome_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d output_tokens: 1 result: satisfied start_event_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d started_at: '2026-02-18T09:30:00.000Z' ManagedAgentsApiErrorDetails: type: object properties: field: description: >- Request field or header responsible for the error, when one can be identified. type: string issues: description: >- Boundary-validation failures as path-prefixed human-readable messages. type: array items: type: string requestId: description: Request correlation identifier for support and log lookup. type: string retryable: description: >- Server advice about failure transience. `true` means transient, `false` means non-transient, and absence gives no advice. Automatic replay is allowed only when this field is not `false` and the operation-specific retry and idempotency contract permits replay. type: boolean additionalProperties: {} description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. ManagedAgentsOutcomeCriterion: description: >- One scored line of a rubric: the criterion, the grader's verdict on it, and the events cited as evidence. Read these to see why an outcome passed or failed rather than only that it did. properties: criterion_id: description: >- Identifies a criterion as its rubric's digest plus its ordinal, so the same rubric reused across sessions scores comparable criteria. Any edit to the rubric changes every id in it. type: string criterion_text: description: The rubric line this verdict scores, as written in the rubric. type: string evidence_event_ids: description: >- Session events (UUIDs) the grader cites as justification, so a reviewer can check the verdict against the transcript instead of trusting it. items: type: string type: array rationale: description: Grader's reasoning for the verdict on this criterion. type: string section: description: >- Rubric heading this criterion sits under, when the rubric is organized into sections. type: string verdict: description: >- Grader's judgment on this criterion, conventionally pass, fail, or not_applicable when the criterion did not apply to this run. Not a closed set: the value is recorded as the grader wrote it. type: string weight: description: >- Relative importance the rubric gives this criterion when aggregating a score. format: double type: number required: - criterion_id - criterion_text - weight - verdict type: object example: criterion_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d criterion_text: example evidence_event_ids: - example rationale: example section: example verdict: example weight: 1.5 securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````