Skip to content
Shortcut: /, ⌘K or Ctrl+K

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.

View as Markdown

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:

FieldDescription
createdAtWhen the request was recorded.
method, routeHTTP 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, resultHTTP status, and failure for any status of 400 or above.
durationMsTime the API spent on the request.
sourceapi for direct requests, mcp for requests made through MCP. mcpTool names the tool.
requestIdThe X-Request-Id response header.
traceIdThe W3C trace ID, also returned in the X-Trace-Id response header.
errorCodeThe error code returned by a failed request.
credentialThe 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#

Shell
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#

ParameterExampleMatches
status404,5xxExact status codes or status classes, up to 10 values.
methodPOST,DELETEHTTP methods, up to 10 values.
route/messaging/:session/messagesOne exact route pattern.
sourcemcpapi or mcp.
credentialIdkey or token IDRequests made by one team key or project token.
requestIdX-Request-Id valueOne request.
traceId32 hexadecimal charactersRequests in one trace.
since, untilRFC 3339 timestampsA 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.

Shell
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:

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.

Shell
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 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 drains also include traceId.

Errors#

StatusCodeCause
400invalid_parameterA filter is malformed, a cursor is invalid or expired, or a cursor was sent with filters.
403missing_scopeThe credential lacks logs:read.
404resource_not_foundThe project does not exist, or a project token tried to read another project.
429rate_limit_exceededMore than 120 reads a minute from one credential. Follow Retry-After.

See List project request logs for the full reference.