Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

Agent: Jobs

Section titled “Agent: Jobs”

Async jobs are gateway-minted records for work that does not complete within a single request, including dispatch turns, workflow runs, long tool calls, and todo message, run, and triage dispatches. Use these endpoints to poll a job’s status, fetch its terminal result, and either cancel a pending or running job or delete a finished record.

GET /api/v1/agent/jobs/{id}

Section titled “GET /api/v1/agent/jobs/{id}”

Get an async job’s status. Returns the status of an async job, covering dispatch turns, workflow runs, and long tool calls. run_id is null during the brief dispatch window for workflow runs. A dispatch or workflow-run job carries the turn_id of the turn it started. Cancelling a dispatch job through the DELETE operation below cancels only that turn.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe job id.

Request

Section titled “Request”
Terminal window
curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/jobs/{id}" \
  -H "Authorization: Bearer $HOODY_TOKEN"

Response

Section titled “Response”

Returns the current job status.

{
  "job_id": "01HXY5J7C2P3V4R5T6S7U8W9X0",
  "kind": "session.input",
  "session_id": "01HXY5J7C2P3V4R5T6S7U8W9Y1",
  "run_id": null,
  "status": "running",
  "turn_id": "01HXY5J7C2P3V4R5T6S7U8W9Z2",
  "created_at": "2025-01-15T10:30:00.123Z",
  "updated_at": "2025-01-15T10:30:05.456Z"
}
FieldTypeDescription
job_idstringGateway-minted job id.
kindstringWhat minted the job. One of session.input, session.workflow, session.question_assist, headless.run, tool.run_gated, todos.message, todos.run, todos.triage.
session_idstringOwning session id. Omitted for a sessionless tool or headless job.
run_idstringWorkflow run id. Null until correlated during the dispatch window.
statusstringJob state. One of pending, running, succeeded, failed, canceled.
turn_idstringThe turn this job dispatched. Present on dispatch and workflow-run jobs; omitted on a sessionless tool or headless job.
errorstringFailure or cancel message when terminal with error. Omitted otherwise.
resultobjectTerminal result payload when present, for example an answer:assist suggestion. Dispatch jobs carry status only.
created_atstringRFC3339 creation time.
updated_atstringRFC3339 last-transition time.

GET /api/v1/agent/jobs/{id}/result

Section titled “GET /api/v1/agent/jobs/{id}/result”

Get an async job’s result. Returns the result of a completed job, or the running status for a job that is still in flight. Dispatch jobs are observed on the session stream, and the result endpoint returns terminal status only.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe job id.

Request

Section titled “Request”
Terminal window
curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/jobs/{id}/result" \
  -H "Authorization: Bearer $HOODY_TOKEN"

Response

Section titled “Response”

For a terminal job, the status, result, and error are returned together. For a pending or running job, only the status and session_id are returned. Read status first to select which shape you got.

{
  "status": "succeeded",
  "result": {
    "answer": "The capital of France is Paris."
  },
  "error": ""
}
FieldTypeDescription
statusstringJob state. One of pending, running, succeeded, failed, canceled. Read this first to select which body shape you got.
resultobjectThe terminal payload, present on every terminal body and null when the job produced none. A dispatch job always returns null here even on success. Absent on a pending or running body.
errorstringThe failure or cancel message, present on every terminal body and empty on success. Absent on a pending or running body.
session_idstringOwning session id. Surfaced on the pending or running body so a caller can go watch the stream; absent from the terminal body.

DELETE /api/v1/agent/jobs/{id}

Section titled “DELETE /api/v1/agent/jobs/{id}”

Cancel a pending or running job, or delete a finished record. Cancels a pending or running async job, or deletes a terminal (succeeded, failed, or canceled) job’s historical record. A pending or running job transitions to canceled and its work is stopped at the source: a sessionless run (headless or long tool call) has its bounded context cancelled, and a session dispatch or workflow turn is stopped by cancelling the session’s active turn (the session and its background tasks are spared). A terminal job’s record is removed. The cancel is authoritative, so a late terminator never flips a canceled job back to succeeded or failed.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe job id.

Request

Section titled “Request”
Terminal window
curl -X DELETE "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/jobs/{id}" \
  -H "Authorization: Bearer $HOODY_TOKEN"

Response

Section titled “Response”

For a cancel, canceled is present and deleted is absent. For a record delete, deleted is present and canceled is absent. Read them for truthiness; do not test either against false.

{
  "status": "ok",
  "canceled": true
}
FieldTypeDescription
statusstringAlways ok on success.
canceledbooleanPresent and true when a pending or running job was transitioned to canceled. Absent on a record delete.
deletedbooleanPresent and true when a terminal job’s historical record was removed. Absent on a cancel.