Refabric Docs

For AI agents: this page is also available as Markdown at https://docs.refabric.com/api-reference/platform/jobs/read-a-job.md, and the index of every page is https://docs.refabric.com/llms.txt.

Platform API › Jobs

Read a job

Where one job is: lifecycle, outcome (null until it ends), progress, and the error of a job that failed — cheap enough to poll.

GEThttps://api.refabric.com/v1/jobs/{job_id}
import os
import requests

url = "https://api.refabric.com/v1/jobs/{job_id}"

headers = {"Authorization": f"Key {os.environ['REFABRIC_API_KEY']}"}

response = requests.get(url, headers=headers)

print(response.json())
{
  "job_id": "9b2f4c1d0e8a",
  "task": "image.expand",
  "lifecycle": "running",
  "outcome": null,
  "progress": {
    "done": 0,
    "phase": "",
    "total": 1
  },
  "metrics": {
    "queued_at": "2026-10-05T09:30:00Z"
  },
  "error": null,
  "api_key_id": "key_8f3a",
  "charge": {
    "credit_type": "refabric_credits",
    "credits": 12,
    "state": "charged"
  },
  "events": [
    {
      "at": "2026-10-05T09:30:00Z",
      "message": "Accepted.",
      "phase": "queued"
    }
  ],
  "input": {
    "body": {
      "prompt": "A linen summer dress"
    },
    "truncated": false
  }
}

Expansions

  • input — the request body that started the job, as you sent it (masked, cut at the kept size). Requests are kept 30 days; after that, and for a job started in the app, input is null.

Authentication. A key with jobs:read: a job and its files are your account's.

Common use cases

  • Poll a job until it ends, then read its result.
  • See which key started a job and what it sent.

See also

  • GET /v1/jobs/{job_id}/result
  • PUT /v1/jobs/{job_id}/cancel

Authorization

Authorization: Key $REFABRIC_API_KEYScope: jobs:read

Parameters

Path parameters

  • stringrequired

Query parameters

  • booleanoptionalDefault: false

    1: add events[] — the job's log {at, phase, message, file?, field?}.

  • array<string>optionalnullable

    input: add input — the request body that started the job, as you sent it (masked, and cut at the kept size, which the answer says). null when the job was started in the app or its request is no longer kept.

Header parameters

  • stringoptional

    The contract version you wrote against (a date). Absent: the current version.

    format: date

  • stringoptional

    Your own id for this request; we answer it back under X-Client-Request-ID.

    max length 128

Response

200 — Done: the answer is in the body.

  • stringrequired

    The job.

    Example: 9b2f4c1d0e8a

  • stringrequired

    The task the job runs.

    Example: image.expand

  • stringrequired

    Where the job is.

    Values

    • queued — Accepted and waiting to start.
    • running — Being made.
    • terminal — Ended. outcome says how.

    Example: running

  • stringrequirednullable

    How the job ended — null until its lifecycle is terminal.

    Values

    • succeeded — It finished; its files are ready.
    • failed — It ended without its result; error says why.
    • cancelled — You cancelled it.
  • objectrequired

    How far the job got.

    Example: {"done":0,"phase":"","total":1}

  • objectrequired

    When it was queued and started, and how long it ran.

    Example: {"queued_at":"2026-10-05T09:30:00Z"}

  • objectrequirednullable

    Why it failed or that it was cancelled, in the shape of every error; null otherwise.

  • stringrequirednullable

    The key that started it; null for work started in the Refabric app.

    Example: key_8f3a

  • objectrequirednullable

    What it costs and whether that is final; null for a job that costs nothing.

    Example: {"credit_type":"refabric_credits","credits":12,"state":"charged"}

  • array<object>optionalnullable

    With logs=1: the job's log, oldest first.

    Example: [{"at":"2026-10-05T09:30:00Z","message":"Accepted.","phase":"queued"}]

  • objectoptionalnullable

    With expand=input: the request that started the job; null when it was started in the app or its request is no longer kept.

    Example: {"body":{"prompt":"A linen summer dress"},"truncated":false}

  • 400 — The request cannot be read as it was sent (a header, the URL or the body's form).
  • 401 — No valid API key was sent.
  • 403 — Your key or your plan does not allow this.
  • 404 — Nothing has this address.
  • 422 — A field is missing or has a value this operation cannot use.
  • 429 — Too many requests: wait for the number of seconds in the Retry-After header.
  • 500 — Something went wrong on our side; retry, and quote the request id if it keeps happening.