# Read and tail request logs

> List a project's API requests, filter them by status, method, route or trace, and follow new requests as they arrive.

The request log lists the API requests made to one project in the last 30
days. Use it to find a failed request, check what a key or token called, or
follow new requests while you test your integration. The Console shows the
same requests under **Logs**.

## What the log contains

Each entry describes one request:

| Field | Description |
| --- | --- |
| `createdAt` | When the request was recorded. |
| `method`, `route` | HTTP method and matched route pattern, such as `/messaging/:session/messages`. A request refused before it reaches an operation shows the prefix, such as `/messaging/*`. Path values are not included. |
| `status`, `result` | HTTP status, and `failure` for any status of 400 or above. |
| `durationMs` | Time the API spent on the request. |
| `source` | `api` for direct requests, `mcp` for requests made through MCP. `mcpTool` names the tool. |
| `requestId` | The `X-Request-Id` response header. |
| `traceId` | The W3C trace ID, also returned in the `X-Trace-Id` response header. |
| `errorCode` | The error code returned by a failed request. |
| `credential` | The credential that made the request: `team_key` or `project_token` with its ID and last four characters, or `client_token` with a null ID and last four. `null` when the key or token no longer exists. |

Entries never include IP addresses, user agents, headers, request bodies or
response bodies.

The log lists requests to the Messaging API and the Graph API, including MCP
tool calls that use them. A request made with a team key is listed under the
project of the number in its path. From the Platform API it lists client token, calling,
SIP trunk and voice requests. Other Platform API requests are not listed.

A request appears about two seconds after it completes. Entries older than 30
days are not listed.

## Before you start

You need:

- a team key (`pmfa_…`) or a project token (`pmfa_pt_…`) with the `logs:read`
  permission. A project token reads only its own project. Client tokens cannot
  read the log.
- the project ID.

`logs:read` is not part of any existing key. Create a new key, or a new
project token, and select **Request logs → Read**. Keys created with every
permission before this permission existed do not include it.

## List recent requests

```bash
curl "https://api.polymorfa.com/platform/projects/$PROJECT_ID/request-logs?status=4xx,5xx&limit=20" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```json
{
  "data": [
    {
      "id": "018f0000-0000-7000-8000-000000000002",
      "projectId": "018f0000-0000-7000-8000-000000000001",
      "createdAt": "2026-10-10T12:00:01.204Z",
      "method": "POST",
      "route": "/messaging/:session/messages",
      "status": 422,
      "durationMs": 41,
      "result": "failure",
      "source": "api",
      "requestId": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30",
      "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
      "errorCode": "invalid_recipient",
      "mcpTool": null,
      "credential": { "type": "project_token", "id": "018f0000-0000-7000-8000-000000000003", "last4": "wxyz" }
    }
  ],
  "page": {
    "nextCursor": "eyJ2Ijox...",
    "hasMore": true,
    "followCursor": "eyJ2Ijox..."
  }
}
```

Entries are newest first. To read older entries, pass `page.nextCursor` as
`cursor`. A cursor keeps the filters of the request that returned it, so do not
send filters with it.

### Filters

| Parameter | Example | Matches |
| --- | --- | --- |
| `status` | `404,5xx` | Exact status codes or status classes, up to 10 values. |
| `method` | `POST,DELETE` | HTTP methods, up to 10 values. |
| `route` | `/messaging/:session/messages` | One exact route pattern. |
| `source` | `mcp` | `api` or `mcp`. |
| `credentialId` | key or token ID | Requests made by one team key or project token. |
| `requestId` | `X-Request-Id` value | One request. |
| `traceId` | 32 hexadecimal characters | Requests in one trace. |
| `since`, `until` | RFC 3339 timestamps | A time range inside the last 30 days. |

## Follow new requests

Every page returns `page.followCursor`. Pass it as `after` to receive only
requests recorded after that page, oldest first. Each response returns a new
`followCursor`; use it on the next call. When no new requests have arrived, the
response has an empty `data` array and the same position.

```bash
curl "https://api.polymorfa.com/platform/projects/$PROJECT_ID/request-logs?after=$FOLLOW_CURSOR" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

A tail loop lists recent requests once, then calls with `after` every one to
two seconds. If `page.hasMore` is `true`, call again at once with the new
cursor. A follow cursor is valid for 24 hours and keeps the filters of the
request that created it.

Each key or token can read the log 120 times a minute. Above that, the API
returns `429` with `rate_limit_exceeded` and a `Retry-After` header. Wait that
many seconds before the next call.

Reads of the request log are not listed in it. The Console's **Logs** page
shows one entry per key or token and hour, with the credential and the number
of reads, so team admins can see who read the log. Console reads appear in
the activity log.

## Use the TypeScript SDK

Use a server-side `Client` with a team key or project token and `logs:read`.
A project client reads its own project. A team client passes `projectId`.
Create the client with a [server credential](https://docs.polymorfa.com/get-started/development-environment#create-a-client):

```typescript
import { Client } from "@polymorfa/sdk";

const client = new Client({
  credential: { type: "organizationApiKey", value: process.env.POLYMORFA_KEY! },
});
```

### List recent requests

```typescript
const page = await client.requestLogs.list({
  projectId: "<project-id>",
  status: ["4xx", "5xx"],
  method: ["POST"],
  limit: 20,
});

for (const log of page.items) {
  console.log(log.createdAt, log.method, log.route, log.status, log.traceId);
}

if (page.nextCursor) {
  const older = await client.requestLogs.list({
    projectId: "<project-id>",
    cursor: page.nextCursor,
  });
}
```

Requests are newest first. A cursor keeps the filters of the page that
returned it; do not pass filters with it. Filters: `status` (codes or classes
such as `404` or `"5xx"`), `method`, `route`, `source`, `credentialId`,
`requestId`, `traceId`, `since` and `until`.

### Follow new requests

`tail` yields new requests as they are recorded, oldest first, until you abort:

```typescript
const controller = new AbortController();

for await (const log of client.requestLogs.tail({
  projectId: "<project-id>",
  status: ["5xx"],
  backfill: 10,
  intervalMs: 2000,
  signal: controller.signal,
})) {
  console.log(log.createdAt, log.route, log.status, log.errorCode, log.requestId);
}
```

Call `controller.abort()` to stop the iterator.

`backfill` yields that many recent requests first (default 0, from 0 to 100).
While no new requests arrive, `tail` polls every `intervalMs` milliseconds
(default 2,000, from 1,000 to 60,000). It reads again at once while more
requests are waiting. When the read limit is reached it waits for
`Retry-After` and continues.

To manage the cursor yourself, call `follow` with `page.followCursor`:

```typescript
const initial = await client.requestLogs.list({
  projectId: "<project-id>",
  limit: 1,
});
let cursor = initial.followCursor;
const next = await client.requestLogs.follow({
  projectId: "<project-id>",
  after: cursor,
});
cursor = next.followCursor;
```

## Use the CLI

Use a team key or project token with `logs:read`.

```bash
polymorfa logs tail --project PROJECT_ID --status 4xx,5xx --method POST
```

Each line shows the time, method, route pattern, status, duration, error code,
source, request ID and trace ID. The command first prints the 10 most recent
matching requests; change this with `--backfill` (0 to 100). It then polls for
new requests every `--poll-interval` seconds (default 2, from 1 to 60) and waits
for `Retry-After` when the read limit is reached. `--max-events` stops after a
fixed number. Press Ctrl-C to stop.

`--json` writes one JSON object per line with `schemaVersion: 1`,
`type: "request"` and the entry in `request`.

Filter with `--status`, `--method`, `--route`, `--source api|mcp`,
`--credential`, `--request-id` and `--trace-id`.

`polymorfa logs list` prints one page, newest first, with the same filters and
`--since`, `--until` and `--limit`. Pass the printed `--cursor` for older
requests, without repeating filters. Its `--json` output uses the standard
read envelope and includes the follow cursor.

## Correlate requests with your traces

Every response includes an `X-Trace-Id` header with a 32-character W3C trace
ID. Browsers can send `traceparent` and read `X-Trace-Id` across origins. To use your own trace, send a [`traceparent`](https://www.w3.org/TR/trace-context/#traceparent-header)
header with the request. When it is valid, Polymorfa records your trace ID, so
you can search for the request with `traceId` and join it to your own tracing
data. Without a valid `traceparent`, Polymorfa generates a trace ID.

Only the trace ID is recorded. Polymorfa does not export its internal spans.
Records sent to [log forwarding](https://docs.polymorfa.com/development/log-forwarding) drains also include
`traceId`.

## Errors

| Status | Code | Cause |
| --- | --- | --- |
| `400` | `invalid_parameter` | A filter is malformed, a cursor is invalid or expired, or a cursor was sent with filters. |
| `403` | `missing_scope` | The credential lacks `logs:read`. |
| `404` | `resource_not_found` | The project does not exist, or a project token tried to read another project. |
| `429` | `rate_limit_exceeded` | More than 120 reads a minute from one credential. Follow `Retry-After`. |

See [List project request logs](https://docs.polymorfa.com/api/request-logs/list-project-request-logs)
for the full reference.
