> ## 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. # Run a canonical automation manually > Atomically freezes the automation and optional payload into one pending run. Explicit manual runs remain available while the automation is paused. The complete HTTP request scope and Idempotency-Key identify the durable result. ## OpenAPI ````yaml /managed-agents/openapi.yaml post /managed-agents/v1/automations/{automationId}/runs openapi: 3.1.0 info: title: Managed Agents API version: 0.13.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/automations/{automationId}/runs: post: tags: - Automations summary: Run a canonical automation manually description: >- Atomically freezes the automation and optional payload into one pending run. Explicit manual runs remain available while the automation is paused. The complete HTTP request scope and Idempotency-Key identify the durable result. operationId: managedAgentsRunAutomation parameters: - description: Stable canonical automation identifier. in: path name: automationId required: true schema: description: Stable canonical automation identifier. format: uuid type: string - description: >- Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry. in: header name: Idempotency-Key required: true schema: description: >- Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry. maxLength: 256 minLength: 1 pattern: ^[!-~]+$ type: string requestBody: content: application/json: schema: $ref: >- #/components/schemas/ManagedAgentsManualAutomationDefinitionRunRequest required: true responses: '200': content: application/json: schema: $ref: >- #/components/schemas/ManagedAgentsAutomationDefinitionRunResponse description: >- Canonical record of one admitted automation run and its frozen execution context. headers: Idempotency-Replayed: description: True when this response replays an earlier completed request. schema: type: boolean style: simple '400': description: The request was rejected by schema or semantic validation. content: application/json: schema: $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': headers: Retry-After: description: Seconds to wait when a matching request is still in progress. schema: type: string style: simple description: >- The request conflicts with the resource state, or with an in-flight idempotent replay. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorConflict' - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyConflict - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyInProgress discriminator: propertyName: code mapping: conflict: $ref: '#/components/schemas/ManagedAgentsApiErrorConflict' idempotency_conflict: $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyConflict idempotency_in_progress: $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyInProgress '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: Seconds the caller should wait before retrying. schema: type: string style: simple description: A rate limit is exhausted. Honor `Retry-After`. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorRateLimitExceeded - $ref: '#/components/schemas/ManagedAgentsApiErrorRateLimited' discriminator: propertyName: code mapping: rate_limit_exceeded: $ref: >- #/components/schemas/ManagedAgentsApiErrorRateLimitExceeded rate_limited: $ref: '#/components/schemas/ManagedAgentsApiErrorRateLimited' '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': headers: Retry-After: description: Seconds the caller should wait before retrying. schema: type: string style: simple description: A dependency is unavailable. Retryable. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable discriminator: propertyName: code mapping: idempotency_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorIdempotencyUnavailable managed_agents_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable service_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable '504': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string description: The service did not respond before the timeout. Retryable. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorGatewayTimeout' components: schemas: ManagedAgentsManualAutomationDefinitionRunRequest: additionalProperties: false description: Structured input for explicitly running a canonical automation. properties: payload: description: >- Optional deliberately open JSON value supplied to this run and frozen in its event context. x-recursion-omission: strategy: absent type: object example: payload: example ManagedAgentsAutomationDefinitionRunResponse: additionalProperties: false description: >- Canonical record of one admitted automation run and its frozen execution context. properties: automationId: description: Automation whose frozen configuration admitted the run. format: uuid type: string automationRunId: description: Stable run identifier and asynchronous status handle. format: uuid type: string automationSnapshot: additionalProperties: {} description: Bounded non-secret automation configuration frozen at admission. type: - object - 'null' completedAt: description: Time session creation succeeded or failed. format: date-time type: string createdAt: description: Time the run was admitted. format: date-time type: string effectiveInitialMessage: description: Complete initial message supplied to the admitted session. type: string error: $ref: >- #/components/schemas/ManagedAgentsAutomationDefinitionRunErrorResponse description: Terminal admission failure. Present only for failed runs. eventContext: additionalProperties: {} description: >- Bounded normalized delivery context or deliberately open manual payload. type: object eventSourceId: description: >- Event source that received the delivery for provider and custom-webhook runs. format: uuid type: string occurrenceAt: description: Schedule occurrence represented by this run. format: date-time type: string promptSnapshot: additionalProperties: {} description: Prompt definition frozen at admission. type: - object - 'null' providerDeliveryId: description: Verified provider delivery identity used for deduplication. type: string sessionId: description: Created managed-agent session. Present only for created runs. format: uuid type: string sourceSnapshot: additionalProperties: {} description: Bounded non-secret source configuration frozen for event runs. type: object status: description: Session-creation outcome. enum: - pending - created - failed type: string statusUrl: description: Canonical member URL for polling this run. type: string triggerId: description: Stored trigger that admitted the run. Absent for manual runs. format: uuid type: string triggerIncarnation: description: Trigger incarnation frozen at admission. Absent for manual runs. minimum: 1 type: integer triggerSnapshot: additionalProperties: {} description: >- Bounded trigger configuration frozen at admission. Absent for manual runs. type: object triggerType: description: Admission kind. enum: - manual - schedule - slack - github - webhook type: string updatedAt: description: Time the run outcome last changed. format: date-time type: string required: - automationRunId - statusUrl - automationId - triggerType - status - automationSnapshot - promptSnapshot - effectiveInitialMessage - createdAt - updatedAt type: object example: automationId: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d automationRunId: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d automationSnapshot: key: example completedAt: '2026-02-18T09:30:00.000Z' createdAt: '2026-02-18T09:30:00.000Z' effectiveInitialMessage: example error: code: example field: example message: example resourceId: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d retryable: true eventContext: key: example eventSourceId: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d occurrenceAt: '2026-02-18T09:30:00.000Z' promptSnapshot: key: example providerDeliveryId: example sessionId: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d sourceSnapshot: key: example status: pending statusUrl: example triggerId: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d triggerIncarnation: 1 triggerSnapshot: key: example triggerType: manual updatedAt: '2026-02-18T09:30:00.000Z' 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorIdempotencyConflict: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - idempotency_conflict message: type: string minLength: 1 description: Human-readable error message. details: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorIdempotencyInProgress: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - idempotency_in_progress message: type: string minLength: 1 description: Human-readable error message. details: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorRateLimited: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - rate_limited message: type: string minLength: 1 description: Human-readable error message. details: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorIdempotencyUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - idempotency_unavailable message: type: string minLength: 1 description: Human-readable error message. details: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsAutomationDefinitionRunErrorResponse: additionalProperties: false description: >- Terminal failure that stopped a canonical automation run before or during session admission. properties: code: description: Stable machine-readable failure code. type: string field: description: Automation field responsible for the failure, when applicable. type: string message: description: Human-readable failure detail safe to show an operator. type: string resourceId: description: Referenced resource responsible for the failure, when applicable. format: uuid type: string retryable: description: >- Whether another admission may succeed without a configuration change. type: boolean required: - code - message - retryable type: object example: code: example field: example message: example resourceId: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d retryable: true securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````