# App runs

An app run is one go at building a campaign's formats for one brand, started from inside InDesign, Figma or Canva, with the design app doing the building. Each format has its own outcome and, if the organisation keeps its work, kept files. A server run's builds are listed here too, with source `headless`. To start a run from the API, see Server runs.

An app run is one go at building a campaign's formats for one brand, started from inside InDesign, Figma or Canva, with the design app doing the building. Each format has its own outcome and, if the organisation keeps its work, kept files. A server run's builds are listed here too, with source `headless`. To start a run from the API, see Server runs.

## The App run object

The run object: a run for one brand, with the outcome of each format.

- `id` (string, required): The run's id (16 hex characters).
- `campaignKey` (string, required): The campaign the run was for.
- `siteCode` (string, required): The brand the run was for.
- `status` (string, required):  One of: `planning`, `planned`, `failed`, `cancelled`.
- `source` (string, required): The app the run came from; `headless` for a run made on the server from a saved master. One of: `indesign`, `figma`, `canva`, `headless`.
- `createdBy` (string, optional): The creating user's id; omitted when unknown.
- `createdByName` (string, required): The member's name; "Member" when they have none, or "Canva user" on a Canva run; "Removed member" when they have left (or no creator was recorded). Never an email.
- `createdAt` (string (date-time), required): When the run started.
- `runId` (string, optional): The run this belongs to; brands started together share it. Omitted when there is none.
- `appVersion` (string, optional): The app build the run came from; omitted when unknown.
- `formats` (array of objects, required): The outcome of each format of the run.
  - `formatKey` (string, required): The format this outcome is for.
  - `status` (string, required): `planned`: laid out; `reviewed`: laid out and checked; `failed`. One of: `planned`, `reviewed`, `failed`.
  - `planSource` (string, required): `planner` when Mestra made the layout, `none` for a failed format. One of: `planner`, `fallback`, `none`.
  - `flags` (array of strings, required): Things the check found worth a look in the layout.
  - `attempts` (integer, required): How many tries the layout took.
  - `reviewApplied` (boolean, required): Whether the review's changes were applied to the layout.
  - `updatedAt` (string (date-time), required): When this outcome last changed.
  - `layout` (string, optional): How the layout was made; absent for a format stored before it was recorded, and for a failed format. One of: `planned`, `shared`, `own`.
  - `layoutReason` (string, optional): Why the layout is `own`; only with `own`. One of: `rules`, `logo`.
  - `failReason` (string, optional): Why a failed format failed, as a code; present only when `status` is `failed` (and absent for formats stored before it was recorded). `layout`: the planner gave up or its answer was unusable. `timeout`: planning ran out of time. `service`: the AI service errored, could not be reached, or anything else. `build`: it was planned, but the app could not build it (`reason` says why). Never text.  One of: `layout`, `timeout`, `service`, `build`.
  - `reason` (one of, optional): Why the format was left out or failed, when it was; see `reasonText` for a sentence.
  - `reasonText` (string, optional): One short sentence for `reason`, built from the format's settings (or, for a build reason, the server's own words naming the run's app); never client copy. Absent for `invalid`.
  - `files` (array of objects, optional): Present when the library holds files for the format (the thumbnail is the one named \_thumb.png).
    - `id` (string (uuid), required): The file's id: fetch it with `GET /library/files/{id}`.
    - `name` (string, required): The file's name.
    - `contentType` (string, required): The file's media type.
    - `size` (integer, required): The file's size in bytes.
  - `reviewNotes` (object, optional): What one layout check of one format or size found. Kept only for organisations that keep their work, and kept encrypted.
    - `outcome` (string, required): `amended`: changes were applied; `nothing`: nothing needed changing; `minor`: only small points; `notes`: points were noted; `not_applied`: the review could not be applied (see `reason`); `none`: no review was made. One of: `amended`, `nothing`, `minor`, `notes`, `not_applied`, `none`.
    - `reason` (string, optional): With not_applied only. One of: `no_visible_change`, `text_order`, `layout_problems`, `layout_rule`.
    - `issues` (array of objects, required): The problems the review found.
      - `elementRef` (string, required): The element's scene id, or empty. A malformed ref, or one longer than 128 characters, is stored empty.
      - `kind` (string, required): What kind of problem it is. One of: `overlap`, `cramped`, `hierarchy`, `misaligned`, `cropBad`, `unreadable`, `overset`, `deadSpace`, `orphan`, `brandNote`.
      - `severity` (string, required): `low`, `medium` or `high`. One of: `low`, `medium`, `high`.
      - `note` (string, required): A short sentence describing the problem.
    - `changes` (array of objects, required): With amended only: each applied change, its element named by role.
      - `name` (string, required): The element changed, named by its role.
      - `requested` (object, required): Each axis is within +-100000; the whole notes payload is at most 32 KiB as stored.
        - `dx` (number, required): Change in left position.
        - `dy` (number, required): Change in top position.
        - `dw` (number, required): Change in width.
        - `dh` (number, required): Change in height.
        - `dTextSize` (number, required): Change in text size.
      - `actual` (object, required): Each axis is within +-100000; the whole notes payload is at most 32 KiB as stored.
        - `dx` (number, required): Change in left position.
        - `dy` (number, required): Change in top position.
        - `dw` (number, required): Change in width.
        - `dh` (number, required): Change in height.
        - `dTextSize` (number, required): Change in text size.
      - `limit` (string, required): What held the change back, if anything: `safe-margin`, `constraint` or `element`; empty when nothing did. One of: \`\`, `safe-margin`, `constraint`, `element`.
      - `by` (string, required): What made the change.
    - `unit` (string, required): The unit of the changes: `px` or `mm`. One of: `px`, `mm`.
    - `flags` (array of strings, required): Flag codes, in the shared vocabulary (`overset:<id>`, `offpage:<id>`, `rotated-fit:<id>`, `export-unavailable:<fmt>`, `focal-unapplied:<id>`, `z-order-failed:<id>`, ...). At most 40, and the whole payload at most 32 KiB as stored (canonical JSON).
- `sourceLink` (object, optional): Where a Canva or Figma run's work lives, until it expires with the run's files.
  - `app` (string, required): `canva` or `figma`: the app the run was made in. One of: `canva`, `figma`.
  - `url` (string (uri), required): A link to the work in that app.
  - `expiresAt` (string (date-time), required, nullable): When the link stops being kept; null under Keep everything.
- `masterName` (string, optional): The name of the saved master the run was built from, when it is pinned to one.

```json
{
  "id": "7d3a9c51e08b42f6",
  "campaignKey": "spring-launch",
  "siteCode": "ESP",
  "status": "planned",
  "source": "indesign",
  "createdBy": "9b2e7a04-61c5-4f1d-8e3a-2c4d6f8a1b22",
  "createdByName": "Alex Morgan",
  "createdAt": "2027-09-02T01:10:44Z",
  "formats": [
    {
      "formatKey": "social-feed",
      "status": "reviewed",
      "planSource": "planner",
      "flags": [],
      "attempts": 1,
      "reviewApplied": true,
      "updatedAt": "2027-09-02T01:11:20Z",
      "layout": "planned",
      "files": [
        {
          "id": "c1d4e8f2-7a36-45b9-b0c8-6e1f3a5d7b33",
          "name": "social-feed.png",
          "contentType": "image/png",
          "size": 412880
        }
      ]
    },
    {
      "formatKey": "social-story",
      "status": "reviewed",
      "planSource": "planner",
      "flags": [
        "overset:headline"
      ],
      "attempts": 2,
      "reviewApplied": false,
      "updatedAt": "2027-09-02T01:11:52Z",
      "layout": "own",
      "layoutReason": "rules"
    }
  ]
}
```

## Retrieve a run

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

Permission: Runs · Read.

Returns the run and what happened to each format: its status, flags and, when the organisation keeps its work, the files kept for it and the run's `sourceLink`. A run of another organisation is a `404`.

### Parameters

- `id` (string, required): The run's id. A run of another organisation is a `404`.

### Returns

The run.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403: “Your role (\<role>) can't \<action>.” (the role is below the route's minimum) or “Choose an organisation first.” (the session has no organisation).
- 404: “job not found”: no such run in this organisation (a run of another organisation is as unknown as a missing one).
- 409 (`api_off`): `409` with code `api_off` (“Turn on the API in Developer → API and MCP first.”): an owner hasn't turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.
- 500: “could not read job”, “could not read the library” or “could not check token”.

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/jobs/string \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## List all runs

`GET /api/v1/jobs`

Permission: Runs · Read.

Returns the organisation's runs, newest first, as summaries: each run's status and counts, without the outcome of each format (Retrieve a run has those). Filter by campaign, site, status, the app it came from, outcome and the day it started; page with `limit` and `offset`. `total` is how many runs match in all.

### Parameters

- `campaign` (string, optional): Filter by campaign key.
- `site` (string, optional): Filter by brand code.
- `status` (string, optional):  One of: `planning`, `planned`, `failed`, `cancelled`.
- `source` (string, optional): Filter by the app the run came from (`headless` for a run made on the server). One of: `indesign`, `figma`, `canva`, `headless`.
- `outcome` (string, optional): `built`: every format built with no flags, and the run neither failed nor cancelled; `flagged`: some format (not failed) has flags; `failed`: the run failed, or some format did.  One of: `built`, `flagged`, `failed`.
- `from` (string (date), optional): First UTC day the run was started, inclusive.
- `to` (string (date), optional): Last UTC day the run was started, inclusive.
- `limit` (integer, optional): 1 to 200.
- `offset` (integer, optional):
- `state` (string, optional): With `grouped=1`: only runs in this state, each run counted once as `building`, else `failed`, else `look` (needs a look), else `ready`. Without `grouped=1` it is not read.  One of: `ready`, `building`, `look`, `failed`.
- `grouped` (string, optional): `1` gives one row per run instead of one per brand: the row adds up the run's brands (matching the filters), with `brands` (their brand codes) and `jobIds` added, and `total` counts runs. A run with no run id is a row on its own.  One of: `1`.

### Returns

Run summaries (no per-format outcomes, but their counts), and how many runs match in all.

An object with:

- `jobs` (array of objects, required):
  - `id` (string, required): The run's id (16 hex characters).
  - `campaignKey` (string, required): The campaign the run was for.
  - `siteCode` (string, required): The brand the run was for.
  - `status` (string, required):  One of: `planning`, `planned`, `failed`, `cancelled`.
  - `source` (string, required): The app the run came from; `headless` for a run made on the server from a saved master. One of: `indesign`, `figma`, `canva`, `headless`.
  - `createdBy` (string, optional): The creating user's id; omitted when unknown.
  - `createdByName` (string, required): The member's name; "Member" when they have none, or "Canva user" on a Canva run; "Removed member" when they have left (or no creator was recorded). Never an email.
  - `createdAt` (string (date-time), required): When the run started.
  - `runId` (string, optional): The run this belongs to; brands started together share it. Omitted when there is none.
  - `appVersion` (string, optional): The app build the run came from; omitted when unknown.
  - `formatCounts` (object, required): The run's formats, each counted once - failed, else flagged (any flag), else built.
    - `built` (integer, required): Formats made with no flags.
    - `flagged` (integer, required): Formats made, but with at least one flag worth a look.
    - `failed` (integer, required): Formats that could not be made.
  - `hasFiles` (boolean, required): The library keeps files (not just a thumbnail) for the run.
  - `notes` (integer, required): How many issues and distinct flags (element flags once per code) the run's kept review notes hold, across its formats.
  - `brands` (array of strings, optional): With `grouped=1`: the brand codes of the run's brands.
  - `jobIds` (array of strings, optional): With `grouped=1`: the ids of the run's brands, by brand code.
- `total` (integer, required): Every run the filters match, limit and offset aside.

### Errors

- 400: “limit must be 1 to 200”, “offset must be 0 or more”, “source must be indesign, figma, canva or headless”, “outcome must be built, flagged or failed”, “state must be ready, building, look or failed”, “from must be a date (YYYY-MM-DD)”, “to must be a date (YYYY-MM-DD)” or “to must not be before from”.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403: “Your role (\<role>) can't \<action>.” (the role is below the route's minimum) or “Choose an organisation first.” (the session has no organisation).
- 409 (`api_off`): `409` with code `api_off` (“Turn on the API in Developer → API and MCP first.”): an owner hasn't turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.
- 500: “could not list jobs” or “could not check token”.

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/jobs \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```
