The agent Jobs endpoints let you poll the status and result of async work dispatched by the agent — workflow runs, long tool calls, dispatch jobs — and cancel pending work or clean up terminal records. Use them whenever you need to observe an in-flight job, retrieve a finished payload, or stop work that has not yet terminated.

Get job status

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

Returns the gateway-minted job record: state, owning session, correlated workflow run id, terminal payload, and timestamps. run_id is null during the brief dispatch window for workflow runs before correlation completes.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Path identifier.
X-Hoody-Cwd	header	string	No	Per-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-Dir	header	string	No	Per-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-Container	header	string	No	Per-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-Realm	header	string	No	Per-request realm selector: global or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realm	query	string	No	Per-request realm selector — the query alias of the X-Hoody-Realm header (read only when the header is absent): global or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Response

200

{
  "job_id": "01HXXXXXXXXXXXXXXXXXXXXXX",
  "kind": "session.workflow",
  "session_id": "sess_01HXXXXXXXXXXXXXXXXXXXXXX",
  "run_id": "run_01HXXXXXXXXXXXXXXXXXXXXXX",
  "status": "succeeded",
  "result": {
    "answer": "Add a unique index on (tenant_id, email) to enforce dedup at the storage layer."
  },
  "created_at": "2025-01-15T10:30:00.000Z",
  "updated_at": "2025-01-15T10:30:42.123Z"
}

400

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
bad_request	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
realm_scope_unsupported	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

403

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
forbidden	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy (e.g. hoody agent … → platform → proxy), not by connecting to the container directly.

404

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
not_found	Not found	The requested resource does not exist.	Verify the path and identifier.

429

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
rate_limited	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the Retry-After header and retry; reduce the request rate.

500

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
internal_error	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

SDK

JavaScript SDK

const job = await client.agent.jobs.getJob("01HXXXXXXXXXXXXXXXXXXXXXX");
console.log(job.status, job.result);

// With optional per-request headers / query params:
await client.agent.jobs.getJob("01HXXXXXXXXXXXXXXXXXXXXXX", {
  realm: "global",
});

cURL

curl -X GET "https://proj-abc123-cont-xyz789-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/jobs/01HXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Accept: application/json"

Get job result

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

Returns the result of a completed job, or the running status. Dispatch jobs are observed on the session stream — the result endpoint returns terminal status only.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Path identifier.
X-Hoody-Cwd	header	string	No	Per-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-Dir	header	string	No	Per-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-Container	header	string	No	Per-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-Realm	header	string	No	Per-request realm selector: global or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realm	query	string	No	Per-request realm selector — the query alias of the X-Hoody-Realm header (read only when the header is absent): global or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Response

200

{
  "status": "succeeded",
  "result": {
    "answer": "Add a unique index on (tenant_id, email) to enforce dedup at the storage layer."
  },
  "session_id": "sess_01HXXXXXXXXXXXXXXXXXXXXXX"
}

400

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
bad_request	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
realm_scope_unsupported	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

403

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
forbidden	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy (e.g. hoody agent … → platform → proxy), not by connecting to the container directly.

404

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
not_found	Not found	The requested resource does not exist.	Verify the path and identifier.

429

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
rate_limited	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the Retry-After header and retry; reduce the request rate.

500

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
internal_error	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

SDK

JavaScript SDK

const result = await client.agent.jobs.getJobResult("01HXXXXXXXXXXXXXXXXXXXXXX");
console.log(result.status, result.result);

cURL

curl -X GET "https://proj-abc123-cont-xyz789-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/jobs/01HXXXXXXXXXXXXXXXXXXXXXX/result" \
  -H "Accept: application/json"

Cancel or delete a job

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

Cancels a pending / running async job, or deletes a succeeded / failed / canceled job’s immutable historical record. A pending/running job transitions to canceled and its work is stopped at the source: a sessionless run (headless / long tool call) has its bounded context cancelled; a session dispatch / workflow turn is stopped via session.cancel (the active turn is cancelled, the session and its background tasks are spared). A terminal job’s record is removed.

Note

The cancel is authoritative — a late terminator never flips a canceled job back to succeeded / failed. An in-flight answer:assist job is NOT independently cancellable (the daemon helper is bound to the question lifecycle with no per-assist cancel on the wire); DELETE returns 409 job_not_cancellable for that kind.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Path identifier.
X-Hoody-Cwd	header	string	No	Per-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-Dir	header	string	No	Per-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-Container	header	string	No	Per-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-Realm	header	string	No	Per-request realm selector: global or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realm	query	string	No	Per-request realm selector — the query alias of the X-Hoody-Realm header (read only when the header is absent): global or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.

Response

200

{
  "status": "ok",
  "canceled": true,
  "deleted": false
}

400

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
bad_request	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
realm_scope_unsupported	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

403

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
forbidden	Forbidden (not via the Hoody proxy)	Forbidden — the request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy (e.g. hoody agent … → platform → proxy), not by connecting to the container directly.

404

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
not_found	Not found	The requested resource does not exist.	Verify the path and identifier.

409

{
  "code": "job_not_cancellable",
  "message": "this job is not independently cancellable"
}

Error Code	Title	Description	Resolution
job_not_cancellable	Job not cancellable	This async job is not independently cancellable: an answer:assist helper runs bound to the question lifecycle and has no per-job cancel path, so the gateway cannot stop it at source.	Let it complete (its suggestion arrives on the session stream / poll the job), or cancel it indirectly by answering the question or cancelling the session turn (POST /sessions/{id}/cancel).

429

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
rate_limited	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the Retry-After header and retry; reduce the request rate.

500

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
internal_error	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

SDK

JavaScript SDK

// Cancel a pending/running job, or delete a terminal job's record:
const outcome = await client.agent.jobs.deleteJob("01HXXXXXXXXXXXXXXXXXXXXXX");
if (outcome.canceled) {
  // transitioned to "canceled"
} else if (outcome.deleted) {
  // terminal record removed
}

cURL

curl -X DELETE "https://proj-abc123-cont-xyz789-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/jobs/01HXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Accept: application/json"