Runs

Report agent and harness activity and progress, and see which runs are still active.

Operation	Request
List runs	`GET /v1/runs`
End run	`POST /v1/runs/{id}/end`
Heartbeat run	`PUT /v1/runs/{id}/heartbeat`

List runs

GET /v1/runs · listRuns

Private to the signed-in account. Live means not ended and a heartbeat received less than three minutes ago. Output and progress are host-reported Unix milliseconds, separate from receipt time. List filters combine with AND; live=false selects expired or ended runs. Results are newest receipt first, with run ID breaking ties. At most 512 runs; reports disappear from the list after 24 hours without a heartbeat, or 24 hours after ending. Use a fresh ID for a new run. Heartbeat body run must match the path ID. Run kind, harness, harness session, computer, and agent stay fixed; output and progress cannot move backward. Send at most once a minute except on status changes. An exact retry within a minute succeeds without extending presence; the same report after a minute refreshes it. Limits: 12 accepted heartbeats per run and 120 per account in a rolling minute, including status changes; 8 KiB heartbeat body. Repeated end requests succeed for a known ID. Heartbeats for an ended ID conflict while its record is kept. Reports grant no execution or steering authority. Responses are private and no-store.

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Name	In	Type	Required	Description
`live`	query	boolean	No
`issue`	query	integer	No

Response

200 — The account's runs or a successful update.

Type: RunList

Field	Type	Required	Description
`runs`	array of RunHeartbeat	Yes
`runs[].run`	string	Yes	An identifier other than . or .. .
`runs[].kind`	one of "app_chat", "terminal", "cloud_work", "landing"	Yes
`runs[].harness`	string	Yes	An identifier other than . or .. .
`runs[].harness_session`	string or null	No
`runs[].computer`	string	Yes	An identifier other than . or .. .
`runs[].issues`	array of integer	No	Default: `[]`.
`runs[].status`	one of "idle", "working", "awaiting_input", "errored"	Yes
`runs[].last_output_at`	integer (int64)	Yes	Unix milliseconds, at most one minute ahead of server time.
`runs[].last_progress_at`	integer (int64) or null	No
`runs[].note`	string or null	No	One line, fewer than 200 UTF-8 bytes, with no control characters.
`runs[].agent`	string or null	No	Agent definition ID, never an agent name.

Errors

Status	Meaning	Body
400, 401, 403, 404, 409, 413, 429, 503	Invalid request, signed out, denied, missing run, run_ended/run_conflict, body too large, rate_limited/quota_exhausted, or unavailable.	AppAccountError

Example

curl 'https://api.openagents.com/v1/runs' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

Runs::list

End run

POST /v1/runs/{id}/end · endRun

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Response

200 — The account's runs or a successful update.

Type: RunOk

Field	Type	Required	Description
`ok`	always true	Yes

Errors

Status	Meaning	Body
400, 401, 403, 404, 409, 413, 429, 503	Invalid request, signed out, denied, missing run, run_ended/run_conflict, body too large, rate_limited/quota_exhausted, or unavailable.	AppAccountError

Example

curl -X POST 'https://api.openagents.com/v1/runs/{id}/end' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

In the Rust SDK

Runs::end

Heartbeat run

PUT /v1/runs/{id}/heartbeat · heartbeatRun

Sign-in: a bearer credential in the Authorization header.

appBearer: A live app sess_ session or oa_sk_ sign-in key. Account-bound oak_ keys are accepted only where the operation declares them and their scopes permit it. API cookies are ignored.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

Content type: application/json

Type: RunHeartbeat

Field	Type	Required	Description
`run`	string	Yes	An identifier other than . or .. .
`kind`	one of "app_chat", "terminal", "cloud_work", "landing"	Yes
`harness`	string	Yes	An identifier other than . or .. .
`harness_session`	string or null	No
`computer`	string	Yes	An identifier other than . or .. .
`issues`	array of integer	No	Default: `[]`.
`status`	one of "idle", "working", "awaiting_input", "errored"	Yes
`last_output_at`	integer (int64)	Yes	Unix milliseconds, at most one minute ahead of server time.
`last_progress_at`	integer (int64) or null	No
`note`	string or null	No	One line, fewer than 200 UTF-8 bytes, with no control characters.
`agent`	string or null	No	Agent definition ID, never an agent name.

Response

200 — The account's runs or a successful update.

Type: RunOk

Field	Type	Required	Description
`ok`	always true	Yes

Errors

Status	Meaning	Body
400, 401, 403, 404, 409, 413, 429, 503	Invalid request, signed out, denied, missing run, run_ended/run_conflict, body too large, rate_limited/quota_exhausted, or unavailable.	AppAccountError

Example

curl -X PUT 'https://api.openagents.com/v1/runs/{id}/heartbeat' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "run": "string",
  "kind": "app_chat",
  "harness": "string",
  "computer": "string",
  "status": "idle",
  "last_output_at": 0
}'

In the Rust SDK

Runs::heartbeat