# Event reference

## job.started

A job left the queue and started (opt-in; once per job).

- `id` (string, _required_) — The event's id — the same on every retry of one delivery. Deduplicate on it: a delivery may arrive more than once.
  Example: `5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90`
- `occurred_at` (string, _required_) — When it happened, ISO-8601 in UTC.
  Example: `2026-10-05T09:30:12Z`
- `event` (string, _required_) — Which event this is.
  Values: `job.started`
  Example: `job.started`
- `api_version` (string, _required_) — The API version the body is written in (`Refabric-Version`).
  Example: `2026-09-29`
- `job_id` (string, _required_) — The job the event is about.
  Example: `9b2f4c1d0e8a`
- `task` (string, _required_) — The task the job runs.
  Example: `image.expand`
- `lifecycle` (string, _required_) — Where the job is.
  Values: `queued` (Accepted and waiting to start.); `running` (Being made.); `terminal` (Ended. `outcome` says how.)
  Example: `running`
- `outcome` (string | null, _required_) — 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.)
- `progress` (object, _required_) — How far the job got.
  Example: `{"done":0,"phase":"","total":1}`
  - `done` (integer, _required_) — Files delivered so far.
    Example: `2`
  - `total` (integer | null, _required_) — Files the job plans to deliver; `null` until it is known.
    Example: `4`
  - `phase` (string, _required_) — What the job is doing now; may be empty.
    Example: ``

```json
{
  "id": "5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90",
  "occurred_at": "2026-10-05T09:30:12Z",
  "event": "job.started",
  "api_version": "2026-09-29",
  "job_id": "9b2f4c1d0e8a",
  "task": "image.expand",
  "lifecycle": "running",
  "outcome": null,
  "progress": {
    "done": 0,
    "phase": "",
    "total": 1
  }
}
```

## job.progress

A job delivered one more output; the payload carries progress {done, total, phase} (opt-in; at most once per delivery, unordered — read progress.done).

- `id` (string, _required_) — The event's id — the same on every retry of one delivery. Deduplicate on it: a delivery may arrive more than once.
  Example: `5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90`
- `occurred_at` (string, _required_) — When it happened, ISO-8601 in UTC.
  Example: `2026-10-05T09:30:12Z`
- `event` (string, _required_) — Which event this is.
  Values: `job.progress`
  Example: `job.progress`
- `api_version` (string, _required_) — The API version the body is written in (`Refabric-Version`).
  Example: `2026-09-29`
- `job_id` (string, _required_) — The job the event is about.
  Example: `9b2f4c1d0e8a`
- `task` (string, _required_) — The task the job runs.
  Example: `image.expand`
- `lifecycle` (string, _required_) — Where the job is.
  Values: `queued` (Accepted and waiting to start.); `running` (Being made.); `terminal` (Ended. `outcome` says how.)
  Example: `running`
- `outcome` (string | null, _required_) — 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.)
- `progress` (object, _required_) — How far the job got.
  Example: `{"done":0,"phase":"","total":1}`
  - `done` (integer, _required_) — Files delivered so far.
    Example: `2`
  - `total` (integer | null, _required_) — Files the job plans to deliver; `null` until it is known.
    Example: `4`
  - `phase` (string, _required_) — What the job is doing now; may be empty.
    Example: ``

```json
{
  "id": "5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90",
  "occurred_at": "2026-10-05T09:30:12Z",
  "event": "job.progress",
  "api_version": "2026-09-29",
  "job_id": "9b2f4c1d0e8a",
  "task": "image.expand",
  "lifecycle": "running",
  "outcome": null,
  "progress": {
    "done": 0,
    "phase": "",
    "total": 1
  }
}
```

## job.succeeded

A job finished and its files are ready.

- `id` (string, _required_) — The event's id — the same on every retry of one delivery. Deduplicate on it: a delivery may arrive more than once.
  Example: `5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90`
- `occurred_at` (string, _required_) — When it happened, ISO-8601 in UTC.
  Example: `2026-10-05T09:30:12Z`
- `event` (string, _required_) — Which event this is.
  Values: `job.succeeded`
  Example: `job.succeeded`
- `api_version` (string, _required_) — The API version the body is written in (`Refabric-Version`).
  Example: `2026-09-29`
- `job_id` (string, _required_) — The job the event is about.
  Example: `9b2f4c1d0e8a`
- `task` (string, _required_) — The task the job runs.
  Example: `image.expand`
- `lifecycle` (string, _required_) — Where the job is.
  Values: `queued` (Accepted and waiting to start.); `running` (Being made.); `terminal` (Ended. `outcome` says how.)
  Example: `running`
- `outcome` (string, _required_) — How the job ended.
  Values: `succeeded`
  Example: `succeeded`
- `progress` (object, _required_) — How far the job got.
  Example: `{"done":0,"phase":"","total":1}`
  - `done` (integer, _required_) — Files delivered so far.
    Example: `2`
  - `total` (integer | null, _required_) — Files the job plans to deliver; `null` until it is known.
    Example: `4`
  - `phase` (string, _required_) — What the job is doing now; may be empty.
    Example: ``
- `result` (object, _required_) — The first page of the job's result, as `GET /v1/jobs/{job_id}/result` answers it.
  Example: `{"files":[],"has_more":false,"job_id":"9b2f4c1d0e8a"}`
  - `job_id` (string, _required_) — The job.
    Example: `9b2f4c1d0e8a`
  - `files` (array<object>, _required_) — The files, in the order the job delivered them.
    - `url` (string, _required_) — Where the file is. A public, permanent address you can open or download.
      Example: `https://files.refabric.com/art/3f2a.png`
    - `media_type` (string, _required_) — The file's standard media type.
      Example: `image/png`
    - `file` (string, _required_) — Its address; pass it to a task as it is.
      Example: `art:3f2a`
    - `task` (string | null, _optional_) — The task that made it.
      Example: `image.expand`
    - `job_id` (string | null, _optional_) — The job that made it.
      Example: `9b2f4c1d0e8a`
    - `created_at` (string | null, _optional_) — When it was made, ISO-8601 in UTC.
      Example: `2026-10-05T09:30:12Z`
    - `data` (object | null, _optional_) — What the file means, in the record vocabulary.
      - `name` (string | null, _optional_) — The record's name.
        Example: `SS27`
      - `description` (string | null, _optional_) — What the record is, in words.
        Example: `A calm palette.`
      - `status` (string | null, _optional_) — Whether it can be used yet.
        Values: `processing` (Still being made or analysed. Read it again later.); `ready` (Finished. It can be passed to a task.); `failed` (It could not be made. Its content is missing.)
        Example: `ready`
      - `colours` (array<object> | null, _optional_) — Its colours.
        Example: `[{"hex":"#1f2a44"}]`
        - `hex` (string, _required_) — The colour as `#rrggbb`.
          Example: `#1f2a44`
        - `name` (string | null, _optional_) — Its name, when known.
          Example: `Navy`
        - `pantone` (string | null, _optional_) — The nearest Pantone code, when known.
          Example: `19-4024 TCX`
      - `items` (array<object> | null, _optional_) — Its parts (a pose preset: its poses and views).
        Example: `[{"type":"fabric"}]`
        - ItemEntry
          - `type` (string, _required_) — What the part is.
            Values: `fabric` (A fabric: its swatch or a photo of it. When the image is a fabric swatch or a photo of a fabric.); `print` (A print or pattern. When the image is a print or pattern.); `look` (A garment or outfit, as a photo or a design. When the image is a garment or an outfit.); `detail` (A close crop of one detail of a look or a product (a collar, a pocket). When the image is a close crop of one detail.); `design` (One cell of a range plan: a design made for one garment line.); `other` (Any other image the record holds. When the image is none of the other kinds.); `product` (A photo of the product itself, as supplied (`view`: which side). When the photo is the product itself; `view` says which side.); `label` (A photo of the product's label (care, size or brand label). When the photo is of the product's label.); `ghost` (The product on an invisible (ghost) mannequin (`view`: which side). When you want the product shown on an invisible mannequin.); `flat` (The product laid flat, as a flat-lay photo (`view`: which side). When you want the product laid flat.); `close_up` (A close-up of the product's fabric and finish (one per product in a shoot). Not `detail`, which is a crop of one trim or component of a look. When you want a close-up of the product's fabric and finish.)
            Example: `fabric`
          - `view` (string | null, _optional_) — Which side it shows.
            Example: `front`
          - `name` (string | null, _optional_) — Its name.
            Example: `Wool twill`
          - `external_id` (string | null, _optional_) — Your own id for it, when you sent one.
            Example: `SKU-1`
          - `description` (string | null, _optional_) — What it is, in words.
            Example: `A navy wool twill.`
          - `url` (string | null, _optional_) — Its image — pass it to a task as it is.
            Example: `https://files.refabric.com/art/3f2a.png`
          - `status` (string | null, _optional_) — Whether it can be used yet.
            Values: `processing` (Still being made or analysed. Read it again later.); `ready` (Finished. It can be passed to a task.); `failed` (It could not be made. Its content is missing.)
            Example: `ready`
        - PresetItem
          - `kind` (string, _required_) — How the entry names what it wants: a saved pose, an image, words, or a product view.
            Example: `view`
          - `ref` (string, _required_) — The pose's address (`pose:…`); empty for a view.
            Example: `pose:812`
          - `angle` (string | null, _required_) — The pose's camera angle.
            Example: `front`
          - `view` (string | null, _required_) — The product view it shows.
            Example: `back`
      - `keywords` (array<string> | null, _optional_) — Words that sum it up.
        Example: `["tailoring"]`
  - `has_more` (boolean, _required_) — More files are on the next page.
    Example: `false`
  - `next_cursor` (string | null, _optional_) — Present when `has_more`: send it as `cursor` to the result read for the rest.
  - `summary` (object | null, _optional_) — Present when the task has words to count.
    - `requested` (integer | null, _optional_) — Outputs asked for.
      Example: `3`
    - `delivered` (integer | null, _optional_) — Outputs made.
      Example: `2`
    - `warnings` (array<object> | null, _optional_) — Notes on what was not made.
      - `code` (string, _required_) — The warning's catalogue code.
        Example: `output_not_produced`
      - `message` (string, _required_) — What happened, in words.
        Example: `This pose was not made.`
      - `field` (string | null, _optional_) — The request field it is about.
        Example: `poses.items[1]`

```json
{
  "id": "5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90",
  "occurred_at": "2026-10-05T09:30:12Z",
  "event": "job.succeeded",
  "api_version": "2026-09-29",
  "job_id": "9b2f4c1d0e8a",
  "task": "image.expand",
  "lifecycle": "running",
  "outcome": "succeeded",
  "progress": {
    "done": 0,
    "phase": "",
    "total": 1
  },
  "result": {
    "files": [],
    "has_more": false,
    "job_id": "9b2f4c1d0e8a"
  }
}
```

## job.failed

A job failed. The payload carries the error.

- `id` (string, _required_) — The event's id — the same on every retry of one delivery. Deduplicate on it: a delivery may arrive more than once.
  Example: `5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90`
- `occurred_at` (string, _required_) — When it happened, ISO-8601 in UTC.
  Example: `2026-10-05T09:30:12Z`
- `event` (string, _required_) — Which event this is.
  Values: `job.failed`
  Example: `job.failed`
- `api_version` (string, _required_) — The API version the body is written in (`Refabric-Version`).
  Example: `2026-09-29`
- `job_id` (string, _required_) — The job the event is about.
  Example: `9b2f4c1d0e8a`
- `task` (string, _required_) — The task the job runs.
  Example: `image.expand`
- `lifecycle` (string, _required_) — Where the job is.
  Values: `queued` (Accepted and waiting to start.); `running` (Being made.); `terminal` (Ended. `outcome` says how.)
  Example: `running`
- `outcome` (string, _required_) — How the job ended.
  Values: `failed`
  Example: `failed`
- `progress` (object, _required_) — How far the job got.
  Example: `{"done":0,"phase":"","total":1}`
  - `done` (integer, _required_) — Files delivered so far.
    Example: `2`
  - `total` (integer | null, _required_) — Files the job plans to deliver; `null` until it is known.
    Example: `4`
  - `phase` (string, _required_) — What the job is doing now; may be empty.
    Example: ``
- `error` (object, _required_) — Why it failed, in the shape of every error.
  - `code` (string, _required_) — The catalogued code.
  - `type` (string, _required_) — What kind of failure.
    Values: `invalid_request` (The request cannot be used as sent; fix it and send again.); `authentication` (No valid API key was sent.); `permission` (Your key or your plan does not allow this.); `not_found` (Nothing of yours has this address, or it was removed.); `conflict` (The request conflicts with the current state of what it names.); `insufficient_credits` (Your balance does not cover this request.); `rate_limited` (Too many requests; wait and retry.); `content_refused` (The inputs were refused.); `processing_failed` (The job ran and failed.); `internal` (Something went wrong on our side.); `warning` (Not an error: a note on a job that succeeded.)
  - `message` (string, _required_) — What happened, in words.
  - `retryable` (boolean, _required_) — Whether the same request may succeed later.
  - `field` (string, _optional_) — The request field it is about, when one is.
  - `docs` (string, _optional_) — The code's page; absent while the docs have no address.
  - `request_id` (string, _optional_) — The request's id, to quote to support.
  - `ctx` (object, _optional_) — Facts about this error, by the keys its code declares (`GET /v1/errors`); absent when there are none. Ignore a key you do not know.
    - `required` (integer, _optional_) — The credits this request needs.
    - `balance` (integer, _optional_) — The credits your balance holds now.
    - `retry_after` (integer, _optional_) — Seconds to wait before the next call.
  - `input` (any, _optional_) — What you sent for `field`, shortened; absent when it is not echoed (a file, an object or a secret never is).
  - `job_id` (string, _optional_) — The job that failed, when a run waited for it (`Prefer: wait`) and it ended in this error. Read it again at `GET /v1/jobs/{job_id}`; absent on every other error.
  - `required` (integer, _optional_, deprecated) — Deprecated: read `ctx.required` (same value).
  - `balance` (integer, _optional_, deprecated) — Deprecated: read `ctx.balance` (same value).

```json
{
  "id": "5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90",
  "occurred_at": "2026-10-05T09:30:12Z",
  "event": "job.failed",
  "api_version": "2026-09-29",
  "job_id": "9b2f4c1d0e8a",
  "task": "image.expand",
  "lifecycle": "running",
  "outcome": "failed",
  "progress": {
    "done": 0,
    "phase": "",
    "total": 1
  },
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## job.cancelled

A job was cancelled.

- `id` (string, _required_) — The event's id — the same on every retry of one delivery. Deduplicate on it: a delivery may arrive more than once.
  Example: `5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90`
- `occurred_at` (string, _required_) — When it happened, ISO-8601 in UTC.
  Example: `2026-10-05T09:30:12Z`
- `event` (string, _required_) — Which event this is.
  Values: `job.cancelled`
  Example: `job.cancelled`
- `api_version` (string, _required_) — The API version the body is written in (`Refabric-Version`).
  Example: `2026-09-29`
- `job_id` (string, _required_) — The job the event is about.
  Example: `9b2f4c1d0e8a`
- `task` (string, _required_) — The task the job runs.
  Example: `image.expand`
- `lifecycle` (string, _required_) — Where the job is.
  Values: `queued` (Accepted and waiting to start.); `running` (Being made.); `terminal` (Ended. `outcome` says how.)
  Example: `running`
- `outcome` (string, _required_) — How the job ended.
  Values: `cancelled`
  Example: `cancelled`
- `progress` (object, _required_) — How far the job got.
  Example: `{"done":0,"phase":"","total":1}`
  - `done` (integer, _required_) — Files delivered so far.
    Example: `2`
  - `total` (integer | null, _required_) — Files the job plans to deliver; `null` until it is known.
    Example: `4`
  - `phase` (string, _required_) — What the job is doing now; may be empty.
    Example: ``
- `error` (object, _required_) — The catalogued `cancelled` error, in the shape of every error.
  - `code` (string, _required_) — The catalogued code.
  - `type` (string, _required_) — What kind of failure.
    Values: `invalid_request` (The request cannot be used as sent; fix it and send again.); `authentication` (No valid API key was sent.); `permission` (Your key or your plan does not allow this.); `not_found` (Nothing of yours has this address, or it was removed.); `conflict` (The request conflicts with the current state of what it names.); `insufficient_credits` (Your balance does not cover this request.); `rate_limited` (Too many requests; wait and retry.); `content_refused` (The inputs were refused.); `processing_failed` (The job ran and failed.); `internal` (Something went wrong on our side.); `warning` (Not an error: a note on a job that succeeded.)
  - `message` (string, _required_) — What happened, in words.
  - `retryable` (boolean, _required_) — Whether the same request may succeed later.
  - `field` (string, _optional_) — The request field it is about, when one is.
  - `docs` (string, _optional_) — The code's page; absent while the docs have no address.
  - `request_id` (string, _optional_) — The request's id, to quote to support.
  - `ctx` (object, _optional_) — Facts about this error, by the keys its code declares (`GET /v1/errors`); absent when there are none. Ignore a key you do not know.
    - `required` (integer, _optional_) — The credits this request needs.
    - `balance` (integer, _optional_) — The credits your balance holds now.
    - `retry_after` (integer, _optional_) — Seconds to wait before the next call.
  - `input` (any, _optional_) — What you sent for `field`, shortened; absent when it is not echoed (a file, an object or a secret never is).
  - `job_id` (string, _optional_) — The job that failed, when a run waited for it (`Prefer: wait`) and it ended in this error. Read it again at `GET /v1/jobs/{job_id}`; absent on every other error.
  - `required` (integer, _optional_, deprecated) — Deprecated: read `ctx.required` (same value).
  - `balance` (integer, _optional_, deprecated) — Deprecated: read `ctx.balance` (same value).

```json
{
  "id": "5f0c6a4e-3b1d-4d7e-9a51-0f2c8d1e7b90",
  "occurred_at": "2026-10-05T09:30:12Z",
  "event": "job.cancelled",
  "api_version": "2026-09-29",
  "job_id": "9b2f4c1d0e8a",
  "task": "image.expand",
  "lifecycle": "running",
  "outcome": "cancelled",
  "progress": {
    "done": 0,
    "phase": "",
    "total": 1
  },
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```