> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trellis.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Job

> Poll the status of a background job

When the agent kicks off a long-running background task (such as generating a schedule from a scope-of-work document), it runs as a **job**. Poll this endpoint for its status while it runs, and refetch the chat once it completes.

<Note>
  Jobs are scoped to both the organization and authenticated member. A job outside either scope returns `404`, never disclosed. Poll while a job is visible; there is no streaming job-progress frame today.
</Note>

<ParamField header="Authorization" type="string" required>
  Bearer token obtained from the [authenticate](/api-reference/authentication/authenticate) endpoint.
</ParamField>

<ParamField path="job_id" type="string" required>
  The job id.
</ParamField>

## Response

<ResponseField name="id" type="string" required>
  The job id.
</ResponseField>

<ResponseField name="kind" type="string" required>
  The job type. Currently the only kind is `sow_generate` (schedule generation from a scope-of-work document); more kinds may be added.
</ResponseField>

<ResponseField name="status" type="string" required>
  One of `queued`, `running`, `succeeded`, `failed`, `cancelled`.
</ResponseField>

<ResponseField name="chat_id" type="string">
  The chat the job belongs to, if any.
</ResponseField>

<ResponseField name="turn_id" type="string">
  The turn the job was submitted from, if any.
</ResponseField>

<ResponseField name="progress" type="object">
  Free-form progress payload, when the worker reports one.
</ResponseField>

<ResponseField name="result_ref" type="object">
  A reference to the job's result (e.g. an artifact id) once it completes.
</ResponseField>

<ResponseField name="error" type="object">
  Failure detail, present when the job failed.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp when the job was created.
</ResponseField>

<ResponseField name="finished_at" type="string">
  ISO 8601 timestamp when the job finished, or `null` while running.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET https://api.trellis.sh/v1/jobs/4c2b909b-2d87-4d37-b34b-829e76485193 \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      "https://api.trellis.sh/v1/jobs/4c2b909b-2d87-4d37-b34b-829e76485193",
      headers={"Authorization": "Bearer YOUR_TOKEN"},
  )
  job = response.json()
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch("https://api.trellis.sh/v1/jobs/4c2b909b-2d87-4d37-b34b-829e76485193", {
    headers: { Authorization: "Bearer YOUR_TOKEN" },
  });
  const job = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "id": "4c2b909b-2d87-4d37-b34b-829e76485193",
    "kind": "sow_generate",
    "status": "running",
    "chat_id": "8f14e45f-ceea-467f-a83c-0a06b8901a45",
    "turn_id": "73e602c9-2058-4a9d-aa0d-3df063ea1d5b",
    "progress": {"stage": "cross_wbs", "detail": "Linking cross-phase dependencies…", "pct": 72, "updated_at": "2026-04-29T18:02:10+00:00"},
    "result_ref": null,
    "error": null,
    "created_at": "2026-04-29T18:00:00+00:00",
    "finished_at": null
  }
  ```

  ```json 404 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "detail": "Job not found"
  }
  ```
</ResponseExample>