# Logs

Processing logs are what each node recorded as a document moved through its flow: the file it fetched, the transformation it ran, the delivery it attempted. They are how you answer "what happened to this document" when a result or a feed entry says something went wrong.

Logs are read one trace at a time. Every notification, submission response, and transaction carries a `traceGuid`, and that is the parameter this endpoint takes.

Logs cover your whole organization, so this endpoint requires a standard API key. Sandbox keys cannot reach it. Log entries are retained for 45 days.

## List Logs for a Trace

```
GET /platform/logs?trace=5ab72145-4a4b-40f6-95de-e2579f163f79
```

Returns the trace's log entries oldest first, which is the order they happened in. The other list endpoints return newest first; this one is meant to be read as a sequence.

Query parameters:

- `trace`: the trace GUID. Required. Without it the request returns `400 missing_parameter`.
- `level`: return only entries at one level, `info`, `warn`, or `error`. Any other value returns `400 invalid_parameter`. A trace can also carry `debug` entries, which come back on an unfiltered read.
- `since`: an ISO 8601 timestamp. Returns entries created at or after it. An unparseable timestamp returns `400 invalid_parameter`.
- `limit`: page size, default 50, capped at 100.
- `cursor`: pagination cursor from a previous response.

The response includes a `logs` array and a `pagination` object:

```json
{
  "logs": [
    {
      "id": "3f8b1c04-2d55-4a7e-9d61-8b7c0a55e912",
      "level": "info",
      "message": "Fetched 850_4471.edi from sftp.acme.example (2.4 KB)",
      "nodeName": "SFTP Fetch",
      "traceGuid": "5ab72145-4a4b-40f6-95de-e2579f163f79",
      "createdAt": "2026-07-01T14:22:33.104Z"
    },
    {
      "id": "6b21af90-77c3-4d18-9f02-1c4e3ab77d55",
      "level": "error",
      "message": "Mapping expression failed: unknown field shipTo",
      "nodeName": "Mapping",
      "traceGuid": "5ab72145-4a4b-40f6-95de-e2579f163f79",
      "createdAt": "2026-07-01T14:22:34.882Z"
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  }
}
```

`nodeName` is the name of the flow node that emitted the entry, as it appears in the flow builder. It is `null` for entries written outside a node.

Pagination works the same way as the feed: while `hasMore` is `true`, pass `nextCursor` back as `cursor` to continue past what you already read. The cursor moves forward through the trace, so a poller watching a run in progress keeps its place across requests.

```bash
# Everything that happened on a trace
curl "https://tediware.com/platform/logs?trace=5ab72145-4a4b-40f6-95de-e2579f163f79" \
  -H "Authorization: Key your-api-key-here"

# Just the failures
curl "https://tediware.com/platform/logs?trace=5ab72145-4a4b-40f6-95de-e2579f163f79&level=error" \
  -H "Authorization: Key your-api-key-here"
```

## The Visibility Lag

Log entries are written to the database in batches and carry the timestamp of the moment they were emitted, so an entry can commit a second or two after the time it records. Entries younger than 5 seconds are withheld for that reason: it keeps an advancing cursor from stepping past a line that has not committed yet.

The practical consequence is that the last few lines of a run you are watching take a few seconds to appear. If the log queue backs up for longer than the lag window, a cursor chain can still miss a line; re-reading the trace from the start without a cursor returns everything.

## Error Responses

```
| Status | Code              | Cause                                                          |
|--------|-------------------|------------------------------------------------------------------|
| 400    | missing_parameter | The trace parameter was not supplied                             |
| 400    | invalid_parameter | The level, since, or cursor value could not be used              |
| 401    | unauthorized      | The API key is missing or invalid                                |
| 403    | forbidden         | The key is a sandbox key. Logs cover the whole organization      |
```

An unknown trace GUID is not an error. It returns an empty `logs` array, the same as a trace whose entries have aged out.

## Rate Limits

Logs draw on the same per-key read budget as the rest of the Platform read API: 240 requests per minute, shared with results, artifacts, and the feed. Exceeding it returns `429` with a `Retry-After` header. See the [Errors](/resources/api-docs/errors) page.