ENendclose

Run an agent

Changed on

Triggers a run of the agent immediately, regardless of its cadence or active flag. The run is created pending and executed asynchronously — poll GET /agents/{id}/runs/{run_id} for status, summary, and output files. Unlike the rest of the agent-management surface, this endpoint also accepts a run's session key, letting one agent kick off another (triggered_by: agent); those requests are refused with 422 when they would loop — the target agent already ran in the trigger chain — or chain more than 5 runs deep.

post/agents/{id}/runs

Request

  • Base URL
    https://api.endclose.com/v1
  • Auth
    API key in header X-API-KEY

Path parameters

idstring required

The unique identifier of the agent

Response

Run created and queued

idstring uuid
scheduled_agent_idstring uuid

The agent this run belongs to

triggered_by'manual' | 'schedule' | 'resume' | 'drop' | 'api' | 'agent'

api for runs started through this API with an API key; agent for runs started by another agent's run using its session key

triggered_by_user_idstring nullable

The user who started a manual run; null for API-triggered runs

triggered_by_run_idstring nullable

For agent-triggered runs: the run whose agent started this one

agent_review_task_idstring nullable

For resume runs: the review task whose resolution this run executes

status'pending' | 'running' | 'waiting' | 'completed' | 'failed' | 'cancelled'
started_atstring date-time nullable
completed_atstring date-time nullable
duration_msinteger nullable
error_messagestring nullable
summarystring nullable

The agent's markdown summary of what it did

modelstring nullable

The model this run executed on

total_input_tokensinteger nullable
total_output_tokensinteger nullable
deliveryobject nullable

The email delivery record for this run's output files, when delivery ran

transcriptobject[]

Full event transcript. Only included when fetching a single run

created_atstring date-time

Changes

  • be0b8ab093c5Revision changes
    • warning

      added the new waiting enum value to the response property for the response status

  • 26e55d00ee4bRevision changes
    • warning

      added the new agent enum value to the response property for the response status

    • info

      added the non-success response with the status

    • info

      removed the non-success response with the status

    • info

      added the optional property to the response with the status