Get a run

GET

/agents/{agentId}/runs/{runId}

const url = 'https://api.asklucy.eu/v1/agents/example/runs/example';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.asklucy.eu/v1/agents/example/runs/example \
  --header 'Authorization: Bearer <token>'

Authorizations

zitadel

Parameters

Path Parameters

agentId

required

string

/^agt_[A-Za-z0-9]+$/

runId

required

string

/^run_[A-Za-z0-9]+$/

Responses

200

application/json

object

required

string

agent_id

required

string

version

required

The agent’s version this run used.

integer

trigger_id

required

The trigger that started it; null for manual runs.

string | null

trigger_type

string | null

Allowed values: webhook schedule

triggered_by

required

Who started it, a user ID (manual) or the trg_ ID.

string

identity

required

Whom the agent acts as.

owner: its creator, with exactly their access (their memory, their Microsoft 365, their quotas). Its runs are their conversations: they can read and continue them as themselves.
service: itself (its ID is its principal). It reaches only what it was given: its knowledge files and the tools below, never anyone’s Microsoft 365. Only org_admins create and see service agents; their runs are read-only.

string

Allowed values: owner service

status

required

queued waits for the agent’s run in progress; skipped: a schedule fired while a run was still going, so this time didn’t run.

string

Allowed values: queued running succeeded failed cancelled skipped

input

required

The trigger’s fixed input, or a manual run’s input. Null for none.

payload

required

A webhook run’s request body (JSON, or a string). Data, never instructions. Null otherwise.

output

required

One of:

object
null

object

text

required

The answer’s text (its text parts, in order).

string | null

files

required

Files the run made (the answer’s output files).

Array<object>

object

required

string

name

required

string

content_type

required

string

size_bytes

required

integer

usage

required

object

steps

required

Tool calls.

integer

input_tokens

required

integer

output_tokens

required

integer

error

required

Why it failed or was skipped. Codes: those of Message.error (internal, timeout, interrupted, rate_limited, unavailable), and time_limit (max_minutes reached), quota_exceeded, agent_disabled (it was disabled or deleted while queued), not_allowed (its identity may no longer use agents), busy (skipped: a run was still going), conversation_deleted (its conversation was deleted while it ran).

object

code

required

string

message

required

string

conversation_id

required

The run’s conversation, once it is running. Owner runs are the owner’s conversations; service runs are read-only, for org_admins.

string | null

message_id

required

The answer that is the run (follow its events while running).

string | null

callback

The result’s delivery to the trigger’s callback_url, when it has one.

object

status

required

failed after 24 hours of retries.

string

Allowed values: pending delivered failed

attempts

required

integer

last_error

string | null

delivered_at

string | null format: date-time

created_at

required

string format: date-time

started_at

required

string | null format: date-time

finished_at

required

string | null format: date-time

Example

{
  "id": "run_2Wc8LmQz5RtYp1Xv7NsK",
  "trigger_type": "webhook",
  "identity": "owner",
  "status": "queued",
  "callback": {
    "status": "pending"
  }
}

401

Missing, expired or invalid token.

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

404

No such object in your organization.

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.