Jobs

Retrieve the status and result of any async Pi job by ID, with optional long-polling and result expansion.

Jobs

GET /api/v1/jobs/:id

All heavyweight Pi operations are async. Every POST endpoint that returns 202 Accepted gives you a job_id. Use this endpoint to poll for status, retrieve the completed result, or long-poll until the job reaches a terminal state.

Request

curl

# Basic status poll
curl -X GET "$PI_BASE_URL/api/v1/jobs/7b8c9f2f-8d7a-4a39-8d8d-1cd4d11f8a7a" \
  -H "Authorization: Bearer $PI_API_KEY"

# Long-poll with timeout
curl -X GET "$PI_BASE_URL/api/v1/jobs/7b8c9f2f-8d7a-4a39-8d8d-1cd4d11f8a7a?wait_for_completion=true&timeout_seconds=20" \
  -H "Authorization: Bearer $PI_API_KEY"

# With result expansion and diagnostics
curl -X GET "$PI_BASE_URL/api/v1/jobs/7b8c9f2f-8d7a-4a39-8d8d-1cd4d11f8a7a?expand=brand&include=diagnostics" \
  -H "Authorization: Bearer $PI_API_KEY"

Path parameters

id · string · required

UUID of the job returned by any async Pi endpoint. Returns 404 if the job does not exist or belongs to a different organization.

Query parameters

wait_for_completion · boolean

When true, Pi holds the HTTP connection open until the job reaches completed or failed, or until timeout_seconds elapses. Use on backend/server clients to eliminate polling loops. Avoid in browser loops where short polling is simpler or on platforms with strict request timeout limits.

timeout_seconds · number

Long-poll timeout window in seconds. Range: 1–30. Defaults to 20. Only applies when wait_for_completion=true.

expand · string

Expand a related resource into the response.

• "brand" — loads the brand row when result_url is brands/{id}
• "avatar" — adds avatar.image_url for completed avatar jobs
• "ad" — adds ad.image_url for campaign ad generation, edit, and localization jobs
• "diagnostics" — includes step diagnostics for orchestration debugging

include · string

Alias of expand. Accepts the same values.

fields · string

Comma-separated list of job fields to return, e.g. fields=id,status,result_url. Use for lightweight status-only polling to reduce bandwidth and parsing cost.

Response fields

id · string

Request envelope ID, e.g. "req_pi_...".

object · string

Always "job".

status · string

Top-level job status. One of "queued", "processing", "completed", "failed".

created_at · integer

Unix timestamp when the request was received.

data · object

The full job record.

Show data fields

data.id · string

UUID of the job.

data.org_id · string

UUID of the owning organization.

data.type · string

Job type identifier, e.g. "brand_extraction", "health_triage", "neuro_decode".

data.status · string

One of "queued", "processing", "completed", "failed".

data.payload · object

Job payload. For completed jobs this contains output with the full result. For in-progress jobs this may contain a phase string.

data.result_url · string | null

Relative resource URL for the result when applicable, e.g. "brands/<id>". null until the job completes.

data.error_log · string | null

Error details when status is "failed". null otherwise.

data.created_at · integer

Unix timestamp when the job record was created.

data.updated_at · integer

Unix timestamp of the most recent status change.

data.expanded · object

Present when expand or include is set and the job is completed. Contains the requested expanded resource under its key (e.g. expanded.brand).

Response examples

Processing:

{
  "id": "req_pi_6f2d...",
  "object": "job",
  "status": "processing",
  "created_at": 1760000000,
  "data": {
    "id": "7b8c9f2f-8d7a-4a39-8d8d-1cd4d11f8a7a",
    "org_id": "30c0342f-4f28-4a13-9d63-5f5a10f57cc6",
    "type": "brand_extraction",
    "status": "processing",
    "payload": { "phase": "phase_c_structuring" },
    "result_url": null,
    "error_log": null,
    "created_at": 1760000000,
    "updated_at": 1760000020
  }
}

Completed:

{
  "id": "req_pi_8a4c...",
  "object": "job",
  "status": "completed",
  "created_at": 1760000100,
  "data": {
    "id": "7b8c9f2f-8d7a-4a39-8d8d-1cd4d11f8a7a",
    "org_id": "30c0342f-4f28-4a13-9d63-5f5a10f57cc6",
    "type": "brand_extraction",
    "status": "completed",
    "payload": { "phase": "completed", "brand_id": "1c26bcfa-e50e-4800-a7df-5b97db5fd50c" },
    "result_url": "brands/1c26bcfa-e50e-4800-a7df-5b97db5fd50c",
    "error_log": null,
    "created_at": 1760000000,
    "updated_at": 1760000088
  }
}

Completed with expand=brand:

{
  "id": "req_pi_8a4c...",
  "object": "job",
  "status": "completed",
  "created_at": 1760000100,
  "data": {
    "id": "7b8c9f2f-8d7a-4a39-8d8d-1cd4d11f8a7a",
    "status": "completed",
    "payload": { "phase": "completed", "brand_id": "1c26bcfa-e50e-4800-a7df-5b97db5fd50c" },
    "result_url": "brands/1c26bcfa-e50e-4800-a7df-5b97db5fd50c",
    "error_log": null,
    "expanded": {
      "brand": {
        "id": "1c26bcfa-e50e-4800-a7df-5b97db5fd50c",
        "name": "apple.com",
        "primary_hex": "#000000",
        "secondary_hex": "#F5F5F7"
      }
    }
  }
}

Job statuses

Status	Meaning
queued	Job is waiting to be picked up by the worker
processing	Worker is actively executing the job
completed	Job finished successfully; data.payload.output contains the result
failed	Job failed; data.error_log contains the error details

Long-polling guidance

Use wait_for_completion=true on backend/server clients to reduce polling round-trips. Do not use it in browser loops where short incremental polling is simpler, or on platforms with strict request timeouts that are shorter than 20 seconds.

Security

The endpoint returns 404 when the job does not exist or when the job belongs to a different organization. This prevents job ID enumeration across tenants.