# List decisions for this Site, newest first, one page at a time

`GET /api/v1/decisions.json` · operationId `listDecisions`

For developers: your server sends this request with a server key; it is not a button in the dashboard. To see the same information without code, open **Control › Approvals › History** in the dashboard.

Ordered by created time, newest first (ties by decision ID). Follow page.nextCursor until it is null to read every decision in the period; page.total counts all matches. from and to take Unix epoch ms or an ISO 8601 date or date-time, like the other exports.

## Authentication

Send `Authorization: Bearer YOUR_SERVER_KEY` (siteServerKey: Site server key in Authorization: Bearer <key> (the scheme is case-insensitive and required; a bare key is 401). Shown once on creation or rotation. Publishable keys cannot authenticate). Keep the server key in server-only configuration; never send it to a browser.

## Parameters

- `limit` (query, integer, optional): Decisions per page (1–1000, default 500).
- `cursor` (query, string, optional): page.nextCursor from the previous page. Opaque.
- `from` (query, string, optional): Period start (inclusive): Unix epoch ms or ISO 8601 date or date-time.
- `to` (query, string, optional): Period end (exclusive): Unix epoch ms or ISO 8601 date or date-time.
- `actionId` (query, string, optional)
- `decision` (query, string, optional)
- `verdict` (query, string, optional)
- `accountId` (query, string, optional)
- `userId` (query, string, optional)
- `sessionId` (query, string, optional)
- `purpose` (query, string, optional)
- `review` (query, "waiting" | "approved" | "rejected" | "expired" | "cancelled", optional): What became of a held decision: waiting, approved, rejected (closed as expired left out), expired (closed as expired) or cancelled.
- `q` (query, string, optional): Search (case-insensitive): part of the account ID or account name, user ID, action ID or name, agent name or session ID.

## Responses

- **200**: Decisions · body `object`
- **400**: bad_request: the request is invalid; message says what to fix and field names the request field · body `Error`
- **401**: unauthorized (missing or invalid server key, missing Bearer scheme) · body `Error`
- **403**: forbidden: the call came from a browser page or another Site; call from your server with this Site’s server key · body `Error`
- **404**: not_found: nothing with this ID on this Site (or it is past retention), or an unknown path · body `Error`
- **429**: rate_limited: wait for Retry-After · body `Error` · headers `Retry-After`
- **500**: internal_error: fail the protected action; do not retry automatically · body `Error`
- **503**: service_unavailable: temporarily unavailable; only verify retries · body `Error`

### Success body fields

- `version` ("1", required)
- `siteId` (string, required)
- `decisions` (object[], required)
- `page` (object, required)
- `page.limit` (integer, required) · minimum 1, maximum 1000
- `page.total` (integer, required) · minimum 0
- `page.nextCursor` (string | null, required)

Failures are not verdicts. Error bodies follow the `Error` schema: `code` is one of `bad_request`, `unauthorized`, `session_reinit_required`, `forbidden`, `not_found`, `conflict`, `identity_required`, `payload_too_large`, `rate_limited`, `internal_error`, `service_unavailable`, `request_failed`, `approval_invalid`, `approval_used`, `approval_expired`, `approval_mismatch`, `step_up_not_held`, `step_up_mismatch`, `step_up_settled`, `step_up_expired`, `step_up_superseded`, `agent_tokens_disabled`, `tool_not_approved`, `tool_not_read_only`. [Errors and retries](/docs/errors) explains each code and what to do.

## Example

```sh tab=curl
curl -sS -X GET 'https://app.trytelltale.dev/api/v1/decisions.json' \
  -H "Authorization: Bearer $TELLTALE_SERVER_KEY"
```

```js tab=fetch
const response = await fetch("https://app.trytelltale.dev/api/v1/decisions.json", {
  method: "GET",
  headers: {
    Authorization: 'Bearer ' + process.env.TELLTALE_SERVER_KEY
  },
  signal: AbortSignal.timeout(5000)
});
const result = await response.json();
```

Machine-readable contract: [openapi.json](https://app.trytelltale.dev/openapi.json). Request builder: the [API explorer](/docs/api-explorer) shows every operation as curl; it sends requests only on a local dashboard.