# API: Runs and audit

Recorded calls, the Change history and exports of both.

Part of the API reference: requests carry a personal access token as `Authorization: Bearer <token>`, and bodies and answers are JSON.

- [API reference](https://typefuse.dev/guides/api-reference)
- [Try it in the API console](https://api.typefuse.dev/docs)

## Runs

### GET /v1/organisations/{org}/decisions/{slug}/runs

**List runs.**

target narrows to draft runs or runs of published versions; environment narrows further.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |

**Query**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `target` | `string`, one of `draft`, `version`, `all` | Optional |  |
| `environment` | `string` | Optional |  |
| `reference` | `string` | Optional |  |
| `limit` | `integer` | Optional |  |
| `offset` | `integer` | Optional |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `runs` | `array` | One page, newest first. `?environment=` takes "all", "production", "draft" (the Sandbox, where draft runs are filed) or a comma-separated list. |
| `total` | `integer` | Every run the filter matches, across all pages. |
| `byEnvironment` | `array of { "environment": string, "runs": integer, "failed": integer }` |  |

```sh
curl "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/runs" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"
```

### GET /v1/organisations/{org}/decisions/{slug}/runs/{runId}

**Get a run.**

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `slug` | `string` | Required |  |
| `runId` | `string` | Required |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `versionId` | `string or null` | Null when the run executed the draft; see draftHash. |
| `draftHash` | `string or null` |  |
| `role` | `string or null`, one of `primary`, `variant`, `compatible`, `shadow` | For served runs, which part of the deployment this was; null otherwise. |
| `environment` | `string` |  |
| `source` | `string` |  |
| `actorType` | `string` |  |
| `actorId` | `string` |  |
| `startedAt` | `string` |  |
| `latencyMs` | `integer` |  |
| `input` | `string or object or array` | Dynamic TypeSafe state: a string, object, or array, checked by state_schema. |
| `answers` | `object or null` | Native TypeSafe answers, keyed by question id; a list in item order for an `each` question. |
| `inputTokens` | `integer or null` | Input tokens, as the provider reported them. |
| `outputTokens` | `integer or null` |  |
| `itemCount` | `integer or null` | Items judged by per-item (`each`) questions; null for a Decision without them. |
| `status` | `string` |  |
| `error` | `string or null` |  |
| `applicationId` | `string or null` | The calling software (its key's Application); null for sandbox and test runs. |
| `reference` | `object or null` | What the call was about, in the caller's terms. |
| `reference.type` | `string` |  |
| `reference.id` | `string` |  |
| `correlationId` | `string or null` | The thread of calls it belongs to. |
| `sealId` | `string or null` | The seal that fixed its content in the audit chain; null until the next seal. |
| `responseOrigin` | `string or null`, one of `provider`, `caller` | Where the provider's response came from: `provider` when TypeFuse received it from TypeSafe itself (Managed, BYOK), `caller` when the caller reported it (Relay, and the removed record-only mode). Null for runs from before it was recorded. Included in the run's seal. |
| `planHash` | `string` |  |
| `completedAt` | `string` |  |
| `state` | `object` | The state exactly as sent to the provider. |
| `provider` | `string` |  |
| `providerModel` | `string or null` |  |
| `providerRequestId` | `string or null` |  |
| `usage` | `object or null` |  |
| `usage.inputTokens` | `integer` |  |
| `usage.outputTokens` | `integer` |  |
| `proof` | `object` | On a single run: its content hashes and seal. |
| `proof.planHash` | `string` |  |
| `proof.inputHash` | `string or null` |  |
| `proof.stateHash` | `string or null` |  |
| `proof.answersHash` | `string or null` |  |
| `proof.seal` | `object or null` |  |
| `versionNumber` | `integer or null` | On a single run: the number of the version it ran (`versionId`'s), null for a draft run. |
| `servedBy` | `object or null` | On a single served call: the deployment that answered it, who asked for it and who approved it. Null for Sandbox, Test set and Evaluation runs. |
| `servedBy.deploymentId` | `string` |  |
| `servedBy.liveAt` | `string` | When the deployment went live. |
| `servedBy.requestedBy` | `object or null` | The person or deploy token that asked for it; null when neither is known any more. |
| `servedBy.approvedBy` | `string or null` |  |
| `servedBy.approvedAt` | `string or null` |  |
| `servedBy.selfApproved` | `boolean` | The person who approved it also asked for it (the only owner or admin). |
| `notStored` | `string` | Present when the run's stored input and the state sent to the model have expired under the plan's retention (or the Sandbox's): the sentence that says so. The run keeps its answers, hashes and seal; `input` is then empty and `state` is `{}`. |

```sh
curl "https://api.typefuse.dev/v1/organisations/acme/decisions/refunds/runs/<runId>" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"
```

## Audit and exports

### GET /v1/organisations/{org}/audit

**Read the audit trail.**

The audit trail, newest first. Filters: type, subjectType, subjectId, actor (user id), decision (slug), before (event id), limit.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |

**Query**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | Optional |  |
| `subjectType` | `string` | Optional |  |
| `subjectId` | `string` | Optional |  |
| `actor` | `integer` | Optional |  |
| `decision` | `string` | Optional |  |
| `before` | `string` | Optional |  |
| `limit` | `integer` | Optional |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `events` | `array` |  |
| `nextBefore` | `string or null` | Pass as `before` for the next page; null at the end. |
| `types` | `array of string` | Event types seen in this organisation. |

```sh
curl "https://api.typefuse.dev/v1/organisations/acme/audit" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"
```

### GET /v1/organisations/{org}/exports

**List exports.**

The organisation's exports, newest first; with `decision` (a slug), only those narrowed to that Decision. Owners, admins and viewers.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |

**Query**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `decision` | `string` | Optional |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `exports` | `array` | Newest first, the latest fifty. |

```sh
curl "https://api.typefuse.dev/v1/organisations/acme/exports" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"
```

### POST /v1/organisations/{org}/exports

**Start an export.**

Exports from Audit. Owners, admins and viewers. A small export is built while the request waits (201, status ready, with a downloadUrl); a larger one is queued (202) and the person is notified when it is ready. 413 EXPORT_TOO_LARGE past 50,000 rows (5,000 with inputs and outputs). Each is recorded as an ExportCreated audit event.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |

**Body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | `string`, one of `calls`, `changes`, `evidence` | Required |  |
| `format` | `string`, one of `csv`, `json`, `zip` | Required | csv or json for calls and changes; zip for an evidence pack. |
| `from` | `string or integer` | Optional | ISO 8601 or unix milliseconds, inclusive. |
| `to` | `string or integer` | Optional | ISO 8601 or unix milliseconds, exclusive. |
| `decision` | `string` | Optional | A Decision's slug; required for an evidence pack. |
| `environments` | `array of string` | Optional | Environment slugs; "sandbox" (or "draft") for Sandbox runs. |
| `includePayloads` | `boolean` | Optional | Calls and evidence packs: include each call's input and the state sent to the model, where still stored. |

**Answer (201)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `kind` | `string`, one of `calls`, `changes`, `evidence` |  |
| `format` | `string`, one of `csv`, `json`, `zip` |  |
| `status` | `string`, one of `queued`, `running`, `ready`, `failed`, `expired` | queued and running while it is built; ready to download; failed; expired once its file is deleted. |
| `what` | `string` | What it holds, in words. |
| `filters` | `object` | What an export was narrowed to. |
| `filters.from` | `string or null` | ISO 8601, inclusive; null for no start. |
| `filters.to` | `string or null` | ISO 8601, exclusive; null for no end. |
| `filters.decision` | `string or null` | A Decision's slug. |
| `filters.environments` | `array of string or null` | Environment slugs ("sandbox" for the Sandbox); null for every environment. |
| `filters.includePayloads` | `boolean` | Calls only: each call's input and the state sent to the model, where still stored. |
| `rows` | `integer or null` | Calls or changes in the file; for an evidence pack, the calls in its period. |
| `sizeBytes` | `integer or null` |  |
| `filename` | `string or null` |  |
| `error` | `string or null` |  |
| `background` | `boolean` | Built after the response; the person is notified when it is ready. |
| `requestedBy` | `object` |  |
| `requestedBy.id` | `integer` |  |
| `requestedBy.name` | `string` |  |
| `createdAt` | `string` |  |
| `completedAt` | `string or null` |  |
| `expiresAt` | `string or null` | When the file is deleted: seven days after it is ready. |
| `downloadUrl` | `string or null` | A signed link that downloads the file without signing in, valid until downloadExpiresAt (at most an hour). |
| `downloadExpiresAt` | `string or null` |  |

```sh
curl -X POST "https://api.typefuse.dev/v1/organisations/acme/exports" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind":"calls","format":"csv"}'
```

### GET /v1/organisations/{org}/exports/{id}

**Get an export.**

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `id` | `string` | Required |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `kind` | `string`, one of `calls`, `changes`, `evidence` |  |
| `format` | `string`, one of `csv`, `json`, `zip` |  |
| `status` | `string`, one of `queued`, `running`, `ready`, `failed`, `expired` | queued and running while it is built; ready to download; failed; expired once its file is deleted. |
| `what` | `string` | What it holds, in words. |
| `filters` | `object` | What an export was narrowed to. |
| `filters.from` | `string or null` | ISO 8601, inclusive; null for no start. |
| `filters.to` | `string or null` | ISO 8601, exclusive; null for no end. |
| `filters.decision` | `string or null` | A Decision's slug. |
| `filters.environments` | `array of string or null` | Environment slugs ("sandbox" for the Sandbox); null for every environment. |
| `filters.includePayloads` | `boolean` | Calls only: each call's input and the state sent to the model, where still stored. |
| `rows` | `integer or null` | Calls or changes in the file; for an evidence pack, the calls in its period. |
| `sizeBytes` | `integer or null` |  |
| `filename` | `string or null` |  |
| `error` | `string or null` |  |
| `background` | `boolean` | Built after the response; the person is notified when it is ready. |
| `requestedBy` | `object` |  |
| `requestedBy.id` | `integer` |  |
| `requestedBy.name` | `string` |  |
| `createdAt` | `string` |  |
| `completedAt` | `string or null` |  |
| `expiresAt` | `string or null` | When the file is deleted: seven days after it is ready. |
| `downloadUrl` | `string or null` | A signed link that downloads the file without signing in, valid until downloadExpiresAt (at most an hour). |
| `downloadExpiresAt` | `string or null` |  |

```sh
curl "https://api.typefuse.dev/v1/organisations/acme/exports/<id>" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"
```

### GET /v1/organisations/{org}/exports/{id}/download

**Download an export.**

The file itself (CSV, JSON or zip). 409 EXPORT_NOT_READY while it is built; 410 EXPORT_EXPIRED after seven days.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `id` | `string` | Required |  |

It answers with no body.

```sh
curl "https://api.typefuse.dev/v1/organisations/acme/exports/<id>/download" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"
```

### GET /v1/organisations/{org}/exports/{id}/evidence

**Download an evidence pack.**

An evidence pack as the app shows it: the facts its PDF is typeset from, and its files. 404 for other exports.

**Path**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `org` | `string` | Required |  |
| `id` | `string` | Required |  |

**Answer (200)**

| Name | Type | Description |
| --- | --- | --- |
| `export` | `object` | A file exported from Audit: the Decision log ("calls") or the Change history ("changes") as CSV or JSON, or a Decision's evidence pack ("evidence", a zip with a PDF summary). |
| `export.id` | `string` |  |
| `export.kind` | `string`, one of `calls`, `changes`, `evidence` |  |
| `export.format` | `string`, one of `csv`, `json`, `zip` |  |
| `export.status` | `string`, one of `queued`, `running`, `ready`, `failed`, `expired` | queued and running while it is built; ready to download; failed; expired once its file is deleted. |
| `export.what` | `string` | What it holds, in words. |
| `export.filters` | `object` | What an export was narrowed to. |
| `export.rows` | `integer or null` | Calls or changes in the file; for an evidence pack, the calls in its period. |
| `export.sizeBytes` | `integer or null` |  |
| `export.filename` | `string or null` |  |
| `export.error` | `string or null` |  |
| `export.background` | `boolean` | Built after the response; the person is notified when it is ready. |
| `export.requestedBy` | `object` |  |
| `export.createdAt` | `string` |  |
| `export.completedAt` | `string or null` |  |
| `export.expiresAt` | `string or null` | When the file is deleted: seven days after it is ready. |
| `export.downloadUrl` | `string or null` | A signed link that downloads the file without signing in, valid until downloadExpiresAt (at most an hour). |
| `export.downloadExpiresAt` | `string or null` |  |
| `summary` | `object or null` | Null until the pack is ready, after it expires, or for a pack made before packs could be viewed. |
| `summary.organisation` | `object` |  |
| `summary.decision` | `object` | An evidence pack's Decision. |
| `summary.period` | `object` |  |
| `summary.generatedAt` | `string` |  |
| `summary.generatedBy` | `string` |  |
| `summary.definition` | `object` | What the Decision decides, as published in the newest release the pack covers. |
| `summary.live` | `array` |  |
| `summary.evaluations` | `array` |  |
| `summary.approvals` | `array` |  |
| `summary.calls` | `object` |  |
| `summary.proof` | `object` |  |
| `summary.files` | `array` |  |

```sh
curl "https://api.typefuse.dev/v1/organisations/acme/exports/<id>/evidence" \
  -H "Authorization: Bearer $TYPEFUSE_TOKEN"
```
