Runs

Get a run

Changed on

Poll run status and retrieve results. Terminal runs include the resolved provider output.

get/v1/runs/{runId}

Request

  • Base URL: https://api.monid.ai
  • URL: https://api.monid.ai/v1/runs/{runId}
  • Auth: HTTP bearer

Path parameters

runIdstring required

Run identifier (ULID).

Example:01JGXYZABCDEFGHJKMNPQRSTVW

Headers

X-Monid-Agent-Modelstring

Model driving the calling agent. Optional; a value that is empty, longer than 256 characters or not printable ASCII is ignored (never an error).

X-Monid-Agent-Harnessstring

Agent harness or client making the call (e.g. a coding agent, an agent framework). Optional; a value that is empty, longer than 256 characters or not printable ASCII is ignored (never an error).

X-Monid-Agent-Session-Idstring

Caller-side session identifier, so the calls of one agent session (discover → inspect → run → polling) can be correlated. Optional; a value that is empty, longer than 256 characters or not printable ASCII is ignored (never an error).

Response

The run (with output when terminal)

runIdstring required

Run identifier (ULID).

callerstring required

The CREDENTIAL that made the call, as an actor id: API_KEY#<fingerprint> (an API key), X402#<address> (a wallet), RESOURCE#<id> (a webhook-initiated run), USER#<userId> (a session). The user behind it is owner.

ownerstring

User id the run belongs to (billed / attributed). Absent for wallet (x402) and resource-initiated runs, which have no user.

providerstring required
providerNamestring
endpointstring required
status'READY' | 'RUNNING' | 'STOPPING' | 'COMPLETED' | 'FAILED' | 'BLOCKED' | 'STOPPED' | 'TIMED_OUT' required

Run lifecycle status. Always one of the UPPERCASE enum values (e.g. COMPLETED, never completed) — compare case-sensitively. COMPLETED means the provider responded (any HTTP status); FAILED means an infrastructure failure.

stoppableboolean
reasonstring
controlsobject[]
outputunknown
resultCountnumber
billedUnitsnumber
createdAtstring date-time required
startedAtstring date-time
completedAtstring date-time
hintsobject

Example response

{
  "runId": "01JGXYZABCDEFGHJKMNPQRSTVW",
  "caller": "API_KEY#a1b2c3d4",
  "owner": "user_2abc",
  "providerResponse": {
    "httpStatus": 200
  }
}

Changes

  • 47b1a281e325Revision changes
    • warning

      added the new byte enum value to the /// response property for the response status

    • warning

      added the new byte enum value to the ///// response property for the response status

    • warning

      added the new byte enum value to the / response property for the response status

    • warning

      added the new byte enum value to the ///// response property for the response status

    • warning

      added the new voice enum value to the // response property for the response status

  • 631143e91790Revision changes
    • info

      added the new optional header request parameter X-Monid-Agent-Harness

    • info

      added the new optional header request parameter X-Monid-Agent-Model

    • info

      added the new optional header request parameter X-Monid-Agent-Session-Id

    • info

      removed the PROMO_REDEEM_DISABLED enum value from the response property for the response status

    • info

      removed the PROMO_REDEEM_DISABLED enum value from the response property for the response status

    • info

      removed the PROMO_REDEEM_DISABLED enum value from the response property for the response status

    • info

      removed the PROMO_REDEEM_DISABLED enum value from the response property for the response status

    • info

      removed the PROMO_REDEEM_DISABLED enum value from the response property for the response status