---
title: "read_logs"
description: "Generated reference for the management action read_logs: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/read-logs
order: 26
visibility: public
redirects_from: []
---

# read\_logs

Generated automatically from the [published contract sources](/cloud/reference/about/#contract-sources).

A script calls this action over HTTPS at `POST https://tzcloud.turnzero.ai/v1/read_logs`, with a bearer credential and the action's payload as the JSON body. It also accepts `GET`. An MCP connection lists this action as the tool `tzcloud_read_logs`.

OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts ([Sign-in, sessions, and tokens](/cloud/concepts/sign-in-sessions-and-tokens/)).

**Build metadata:** Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.

## Contract description

Read your application's logs for one environment\.

`container` is stdout/stderr, `app` is logging\-package output\. `router` keeps 5xx responses whole within its cap, and `read_status` lists failed paths in `server_errors`\. `all` or no `source` merges stored sources and console by time\. On an all\-source read, any of `level`, `field`, `filter`, `contains` or `until` excludes console lines\.

For `container`, `level` and `field` give `invalid_request`, and `until` is ignored\. It returns `lines`, without `entries`\. Waiting needs `since`\. Without compute, it can return kept failed\-check lines\. A version in flight, or an upload in progress on a deploy target with no history, gives `deploy_in_flight`\. Other refusals use `never_deployed`\.

## More about this action

The store sources, `app`, `platform`, `router`, `egress`, `harness`, and `pool`, are the records the logging service stores in the environment's stream\. Every store source, `app`, `platform`, `router`, `egress`, `harness`, `pool`, and the whole stream, returns `lines` and adds `entries`, the same records parsed, each with its `at`, `level`, `source`, `message`, and any `fields`\. The `platform` source contains the platform's entries about the application, including each scheduled run's outcome\.

The `router` source contains the serving router's records\. Each minute it writes one `legs_ended` record for each invocation kind and outcome, with the count and the duration's sum and maximum\. It keeps whole each `window_ended` request, one that ran past the router's deadline, and each `upstream_ended` request, one that the end of the application's process cut off\. It writes one `source_refused` record for each minute in which the per\-source bound refused requests, with the bound, the count refused, and the number of distinct sources refused\. It writes one `sockets_ended` record per minute for each reason WebSocket connections ended\. That record has the router's close code, null where one side closed, the count, and the duration's sum and maximum in milliseconds\.

A `legs_ended` record with the outcome `answered` also has its `status_class`, `2xx` to `5xx`, so a 500 is never counted with a 200\. Each 5xx response is also kept whole, as an `answered_5xx` record with the `request_id`, the method, the path without its query, the status, the duration, and the serving version\. A 504 for a request whose process had not started listening in time is kept as a `start_timed_out` record instead\. At most twenty of these are kept per application and environment each minute, and the rest are counted only in the `legs_ended` records\.

To find a failed request's records, read its response's `x-request-id` header\. Set `field: "request_id"`, `value` to that header, `since` to the request's start, `wait_seconds: 10`, and omit `source`\. This finds its 5xx router record, where kept, and the `app` entries your code wrote with that field\. A read by `field: "request_id"` with no `source` waits a few seconds more, until the `router` and `app` sources have each answered or no new entry comes\. Console lines have no structured fields\. Read `source: "container"` from the same `since`; add `contains` with the id only where your code prints it\.

The `egress` source contains the outbound proxy's records\. Each minute it writes one `egress_establishments` record for each host, port, outcome, and declared flag, with the count\. For an observed host the manifest does not declare, that record also has the refusal name and, where one exists, its remedy\. The proxy keeps each `egress_refusal` whole\.

The `harness` source contains the connection\-observer records of the runtime harness, the platform's code loaded into the application's process\. The application's own process sends them under its own credential, so they are not attested platform records\. Each minute it writes one `egress_establishments` record for each host, port, and outcome, with the proxied mark and the count\. It keeps each failed `egress_establishment` whole\.

The `pool` source contains a serverless application's function console lines and the pool entry's records of its calls\.

Records arrive with a delay\. A store source's entries arrive within a few seconds, when the logging client flushes on its interval\. The per\-minute records under `router`, `egress`, and `harness` arrive once their minute has ended\. An empty answer has a `detail` that says why\. So does an answer whose window ends inside its source's lag, since its newest records may not have arrived yet\.

The `container` source is the one console read: the process's standard output and standard error\. The `console.log` and `console.error` lines land there, and so do the harness's `window_ended`, `process_ended`, and `harness_refusal` lines\. It is the process's own console, not a stream\. For an environment whose `grain` is `pod`, it is the pod's console, read through the cluster's API server\. After a restart it has the previous container's lines and then the current one's, or the previous container's alone while the current one waits to start\.

A pod's live console ends with the pod, at a scale to zero or a replacement\. The read then returns that pod's ended\-pod lines: the first and last lines each of its processes wrote, marked `[pod-ended]` and placed before the standing pods' lines\. A process ended by a crash, an out\-of\-memory kill, or a SIGKILL keeps none\. For an environment whose `grain` is `container`, it is the provider's console log store, where the window's `process_ended` and `harness_refusal` lines and the logging client's fallback lines land\. A `container` line from the version being replaced has `[retiring]`\.

A `container` read acts on the compute of the environment you name, production where you name none\. Where that environment has no compute, the read can still return the lines a failed health or smoke check kept\. It returns up to 40 of them, with `failed_check`, where nothing is in flight and the newest version failed its health or smoke check with no earlier version serving\. Otherwise it is refused `deploy_in_flight` while a version is in flight, or while an upload to the deploy target is in progress and the environment has no history\. Every other refusal is `never_deployed`\. Where nothing is running and the environment's latest version failed, the detail identifies that failed deploy or promote and, where recorded, gives its step and error\. The failure stays in that version's outcome in `read_status`, including the failed health check's last console lines where the check failed\.

Where the `grain` is `container` and the platform has the direct read enabled, a `container` read also reads each running replica's console directly, once\. Where that direct read succeeds, it returns the newest lines at once\.

On a `container` read, `contains` searches the newest 1,000 lines, ignoring case, and the `detail` says what it searched\. The search runs before the `limit` cut, which keeps whole matches newest first and a cut match's own line\. A `level` or `field` is refused `invalid_request`, because a console line has neither\.

With `wait_seconds` on a store source, the platform reads the store every two seconds\. It replies once a matching entry exists or this many seconds have passed since the call arrived, with `waited_ms`\. An entry already in the window ends the wait at once, so give `since` to wait for entries written after a moment\. Each server holds one wait per application\. This call's wait takes that place\. A concurrent held `read_status` or held act for that application on the same server returns at once\. A wait that finds another call waiting also returns at once, and its empty answer's `detail` starts with a sentence saying it did not wait\.

On a `container` read, `wait_seconds` follows the console instead, up to 40 seconds, so give `since`\. It follows the console of each running replica, three at most, or of the newest pod\. The answer comes once a line that the call's filters accept is written at or after `since`, or at the earlier of `wait_seconds` and 40 seconds\. It has every line read, and `waited_ms`\. The wait needs the direct read enabled\. It cannot wait where that server already holds a wait for the application\. It also cannot wait where that server's waits or follows are full, or where the management API is near its limit\. The read then returns at once as an ordinary `container` read, and its `detail` says why\. Where the limit is reached during the wait, the read replies with the lines read so far\. A crashed process's earlier lines are read without the wait\.

The `filter` argument: `declared` or `undeclared` reads the outbound connections whose host the manifest declares, or does not, as the manifest is at the time of the read\. It reads the proxy's and the harness's per\-minute establishment records, and their whole refusals and failures, within the returned page: the named source's, or every source's where you name none\. The platform's own endpoints, the loopback targets, and the harness's proxied records are left out either way\. Use it to see what to add to the manifest before enforcement is turned on\. Where a `container` read passes `contains`, the filter runs over the lines that matched, among those searched, before the `limit` cut\.

The `since` argument: left out, this bound is open, except on a `container` read\. For an environment that runs as a container, its window then starts 24 hours before the read; for one that runs as a pod, so does its read of the ended\-pod lines\. A null, empty, wrongly typed, or malformed value is refused 400 `invalid_request`, and the detail identifies the member\. A `since` or `until` timestamp's calendar date must exist\. Hours are 00–23, minutes and seconds 00–59, and the offset's hours and minutes 00–23 and 00–59\. Leap seconds and 24:00 are not accepted\. Values are converted to UTC at millisecond precision\.

The `source` argument: `container` reads the process's console, its standard output and standard error, `console.log` and `console.error` among them\. `app` reads only what the application writes through the logging package, and `platform` the platform's entries about it\. `router`, `egress`, `harness`, and `pool` read the records of the serving router, the outbound proxy, the runtime harness's connection observer, and the function pool\. `all`, or no source, reads every store source and, on development or production, the console's lines as `container` entries, merged by time within `limit`\. A line from standard error is at level `error` and any other at `info`; a pod's console does not mark standard error, so every line from a pod is at `info`\. Passing `level`, `field`, `filter`, `contains`, or `until` leaves the console's lines out\. Over MCP, any other value is refused; over the HTTP API, it reads as `all` does\.

The `wait_seconds` argument: the seconds, 1 to 45, that the call waits while a read with this call's filters finds no entry\. A store source is read every two seconds, and a `container` read follows the console, 40 seconds at most\. A value outside 1 to 45 is refused `invalid_request`, and its detail gives the bound\.

The `limit` argument: 100 where none is given\.

Where the `detail` says lines may still be in the ingestion, read again about a minute later\.

## Access and action metadata

```json
{
  "name": "read_logs",
  "resource": "environment",
  "tier": "observe",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "product": "cloud",
  "clients": [
    "bearer",
    "browser_session"
  ],
  "summary": "The environment's log entries written through the logging service, filterable by time, level, message, field, and source. `source` selects one of the stream's sources. `app` is only what the application writes through the logging package; standard output and standard error land under `container`. `platform` is the platform's entries about it, each scheduled run's outcome among them. `router` is the serving router's `legs_ended` records per invocation kind and outcome per minute, its `window_ended` requests whole, and its `upstream_ended` requests whole, each a request an application's process end cut. It also holds its `source_refused` records, one per minute the per-source bound refused requests in. Its `sockets_ended` records are one per minute and reason WebSocket connections ended, with the close code, the count, and the durations. `egress` is the tunnel seat's `egress_establishments` records per host and outcome per minute, an observed host's refusal name and remedy on them, and its refusals whole. `harness` is the runtime harness's connection observer's `egress_establishments` records and its failed `egress_establishment` records, shipped from the application's own process. `all` is every source the logging service stores, with the container's console output merged by time unless you pass `level`, `field`, `filter`, `contains`, or `until`. `container` is the one console read, the named environment's own compute (production where none is given; a pod's live console read through the cluster's API server, after the first and last lines of the environment's ended pods, marked `[pod-ended]`). It is where the process's standard output and standard error land, `console.log` and `console.error` lines among them, beside the `process_ended` and `harness_refusal` lines and the logging client's fallback lines. `filter` is the declared-versus-observed reading: `declared` or `undeclared` against the manifest's egress member, over the aggregated records with the platform endpoints and the loopback targets subtracted. The `legs_ended` record of a leg that got a response carries its `status_class`, and each 5xx response is kept whole as an `answered_5xx` record, under a per-minute cap. A 504 refusing a request whose process had not started listening in time is kept as a `start_timed_out` record instead, under the same cap. Store entries land within a few seconds, and on the container grain a `container` line reaches the log workspace up to about a minute after it is written. On the container grain, where the platform has the direct read enabled, the read also reads each running replica's console directly, once. Where that direct read succeeds, it returns the newest lines at once. A `container` answer is ordered by each line's write time, on the pod grain pod by pod with the ended pods' lines first, and a line from the environment's recorded previous compute carries `[retiring]`. An empty answer, or one whose window ends inside that lag, carries a `detail` saying why. On the container grain, where the direct read is enabled, that `detail` also reports it. It gives the time from which lines were read from the replica directly where any were kept. It says when lines may still be in the ingestion, and gives a failed read's reason. On a `container` read, `contains` searches its newest 1,000 lines, and a `level` or `field` is refused `invalid_request`, a console line carrying neither.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": true,
    "idempotentHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "read_logs",
  "title": "Read app logs",
  "tier": "observe",
  "scenario": "CHI-L0-09",
  "summary": "Read your application's logs for one environment.\n\n`container` is stdout/stderr, `app` is logging-package output. `router` keeps 5xx responses whole within its cap, and `read_status` lists failed paths in `server_errors`. `all` or no `source` merges stored sources and console by time. On an all-source read, any of `level`, `field`, `filter`, `contains` or `until` excludes console lines.\n\nFor `container`, `level` and `field` give `invalid_request`, and `until` is ignored. It returns `lines`, without `entries`. Waiting needs `since`. Without compute, it can return kept failed-check lines. A version in flight, or an upload in progress on a deploy target with no history, gives `deploy_in_flight`. Other refusals use `never_deployed`.",
  "owners": [
    "EGW-L0-17",
    "EGW-L0-15",
    "HST-L0-03",
    "PLD-L0-40",
    "SVC-L0-07",
    "SVC-L0-18",
    "HST-L0-01",
    "PLD-L0-136",
    "PLD-L0-137",
    "MAN-09"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["application"\] |
| /<wbr>properties/<wbr>application | Your account's application `id` from `list_applications`, not its name or label\.<br><br>Type: string |
| /<wbr>properties/<wbr>environment | Default production\. `local` is the caller computer's stream\. Without compute, `container` can return kept failed\-check lines or refuse `deploy_in_flight` or `never_deployed`; read the detail for why\. `container` with local gives `invalid_request`\.<br><br>Type: string |
| /<wbr>properties/<wbr>since | Inclusive timestamp with a time zone: `YYYY-MM-DDTHH:mm[:ss[.fraction]]`, then `Z` or `±HH:mm`\. Fraction has 1–9 digits, T/Z ignore case\. Malformed gives `invalid_request`\. Default open, except 24 hours back for a container environment's console\.<br><br>Type: string |
| /<wbr>properties/<wbr>limit | Newest entries retained, default 100\.<br><br>Type: integer<br>Minimum: 1<br>Maximum: 1000 |
| /<wbr>properties/<wbr>source | `container`: stdout/stderr\. `app`: logging\-package records\. `egress`: outbound proxy\. `harness`: runtime harness\. `pool`: functions\. Also `platform` and `router`\. `all` or absent merges by time\. On an all\-source read, any of `level`, `field`, `filter`, `contains` or `until` excludes console lines\.<br><br>Type: string<br>Allowed values: \["app","platform","router","egress","harness","pool","container","all"\] |
| /<wbr>properties/<wbr>filter | Connections to hosts declared or undeclared in the manifest's `egress` at the read\. Naming `source` selects its page: `egress` reads the proxy's records, `harness` connections made without the proxy\. With no source, the returned page may hold neither\.<br><br>Allowed values: \["declared","undeclared"\] |
| /<wbr>properties/<wbr>until | Inclusive end, with `since` syntax and validation\. Default open\.<br><br>Type: string |
| /<wbr>properties/<wbr>level | Minimum level: `debug`, `info`, `warn` or `error`\. Other values are ignored\.<br><br>Type: string |
| /<wbr>properties/<wbr>contains | Message text\. On `container`, case\-insensitive over the newest 1000 lines, with indented continuation lines, before `limit`\.<br><br>Type: string |
| /<wbr>properties/<wbr>field | Structured field matched with `value`\. Without `value`, any entry with the field\. For a response's `x-request-id`, use `request_id` here, its header as `value`, and no `source`\. This finds stored records, not console lines\.<br><br>Type: string |
| /<wbr>properties/<wbr>value | JSON\-typed equality with `field`, including null\. Omitted matches any entry with the field\.<br><br>Type: \["string","number","boolean","null"\] |
| /<wbr>properties/<wbr>wait\_seconds | Wait for an entry, with `since`\. For `container`, the console is followed for at most 40 seconds\. Out of range gives `invalid_request`\.<br><br>Type: integer<br>Minimum: 1<br>Maximum: 45 |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","lines"\] |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>reference | The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row\. Quote it when you report the call\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{10\}$ |
| /<wbr>properties/<wbr>lines | The answer's lines, oldest first\. From a store source each line renders one entry\. From `container` a line is `<time> <stream> <text>`: the time the process wrote it, then `stdout` or `stderr` on the container grain, or `-` on the pod grain, whose log gives no stream\. On the container grain the lines are ordered by that time; on the pod grain they come pod by pod, the ended pods' lines first\. A line from the compute the environment records as previous, the version being replaced, carries `[retiring]` after its stream; a line of the new version never does\. On the container grain a line the stopped replica wrote at or after the provider's scale to zero carries `[idle-stop]` there instead, and a `[retiring]` line never carries it; the pod grain marks no idle stop\. A read whose window starts after the scale to zero, or one made before the provider's record of the stop arrives, leaves those lines unmarked\. On the pod grain an ended\-pod line, one of the first and last lines each process of an ended pod wrote, carries `[pod-ended]` after its stream, or after `[retiring]` where it carries both\. Ended\-pod lines come before the standing pods' lines, read from `since`, or from 24 hours back where it is absent\. Where the environment has no compute, no version serves, and the newest version's failed health or smoke check kept lines, `container` returns those lines as the check kept them, at most 40, with no line written after the check\.<br><br>Type: array |
| /<wbr>properties/<wbr>lines/<wbr>items | Type: string |
| /<wbr>properties/<wbr>retiring\_lines | Present only on a `container` answer where at least one of `lines` carries the `[retiring]` mark the platform set: how many do\. Those lines are the previous version's, from the compute being replaced, so where this equals the length of `lines` no line returned is the serving version's\. A line the application wrote that opens with `[retiring]` is not counted\.<br><br>Type: integer<br>Minimum: 1 |
| /<wbr>properties/<wbr>detail | Present on an empty answer, saying why nothing was found, and on any answer whose window ends within its source's lag of the read, saying the newest records may not have arrived yet\. A read of all sources that holds entries also carries it, saying after any lag that it includes the container's console output, as an empty one says; on the `local` stream, which has no console to read, neither says so\. Where the read passes `level`, `field`, `filter`, `contains`, or `until`, or its console read was refused, failed, timed out, or found no compute, it says instead that console output is not included and why\. Where the entries of a read of all sources or of `router` hold the router's `answered_5xx` record, the detail gives the `container` read and its `since`\. That `since` is the earliest such record's instant less its duration and five seconds\. The detail also says that the read returns the newest lines after its `since`, so you raise `limit` or add `contains`, and this sentence takes the place of the console sentence\. On the pod grain the read is given for a record of the serving version alone, and the sentence adds that an ended pod keeps its first and last lines\. Where the records there are of another version, the detail gives that version and no read; where they carry none, it says so and gives no read\. On a read of all sources that sentence follows the console sentence\. A `container` read carrying `contains` carries it, opening with the lines searched and matched, what the egress filter kept where given, the number returned where `limit` cut them, and, on the container grain, their span\. It says where the cut left a match's later frames out\. A `container` answer with lines also carries it where the environment is idle now, saying after any lag that the last lines are an idle stop and that the next request starts the application\. Where the platform marked a line of the answer `[retiring]`, the detail ends by saying that such lines are the previous version's, unless that sentence would take it past its budget\. Where a `container` detail would pass its budget, sentences are left out, in a fixed order, until it fits\. The sentence on more instances than a wait followed goes first\. Then go the sentences on missing lines, on the delay before lines reach the log store, on an idle environment, and on a replica not running, stopped, or just restarted\. The `[retiring]` sentence goes next, and the sentence on how a wait ended goes last\. A pod answer says so where a line longer than the 262,144 bytes its read holds was not returned\. Idle is the container app's latest revision holding no replica, or the pod's Deployment scaled to zero, and a halted environment is never idle\. Under `app`, only what the application writes through the logging package lands there, and standard output and standard error land under `container`\. Under `container`, the compute may have scaled to zero, recent lines may still be in the ingestion, `contains` matched none, or `filter` kept none\. Under any other source, no entry is in the window, or none matches the read's filters\. The lag is a few seconds for the store's entries, up to a minute for the per\-minute records under `router`, `egress`, and `harness` and for a container app's console, and none for a pod's console\. On the container grain, where the platform has the direct read enabled, a `container` read also reads each running replica's console directly, once and bounded, and its detail says how that read went\. Where the direct read kept lines, the detail gives the time from which the newest lines were read from the replica directly, and says a later read may return them again with the log workspace's stamp\. The detail says lines may still be in the ingestion where that read reached no replica or did not complete, giving the reason where it failed\. Where it did not complete, the sentence on the delay says instead that the log workspace's lines are those it held at the read, and the reason's sentence says a later read adds lines\. A reason's word longer than 29 characters is cut to 29 characters, ending with `…`, in the detail, and `reason` carries it whole\. It says so too where a replica is not running, stopped, or has just restarted, or where the answer may lack lines\. Where none of those holds and the direct read kept no line, the detail says the replicas' newest lines are in this answer\. An empty answer then says only that the compute may have scaled to zero and written nothing\. Lines still in the ingestion reach the log workspace up to about a minute after the process writes them, so a later read returns them\. A `container` read whose `wait_seconds` did not hold says why, unless its budget leaves that sentence out\. The causes are the place taken, the platform's waits or follows full, the management API near its limit, the direct read off, or, on the pod grain, no pod running to follow\. It also says where more instances run than the three followed\. A `container` answer from a failed health check's kept lines opens with what happened and where `read_status` holds the same lines\. Its `contains`, `filter`, and `limit` sentences give counts alone and no span, since those lines carry no time\.<br><br>Type: string |
| /<wbr>properties/<wbr>reason | Present only where a `container` read's direct read of the replicas did not complete: the reason's one word, whole at any length, such as `timed_out`, `throttled`, `http_503`, or a network error code\. The `detail` gives the same reason, cutting a word longer than 29 characters\. On an answer with lines, or one the filter emptied, it also says the log workspace's lines are those it held at the read, unless its budget leaves that sentence out\. A reason beside lines, `timed_out` among them, applies to the direct read alone; a later read adds lines\. The word comes from the platform's own read of your replicas through the hosting provider, and its cause may not be known\. It does not say whether your application is healthy; `read_status` does\. A stream that responded with a 5xx status, 501 and 505 aside, was asked once more where the read's bound allowed\.<br><br>Type: string |
| /<wbr>properties/<wbr>failed\_check | Present only on a `container` answer where the environment has no compute, no version serves, and the newest version's failed health or smoke check kept a record\. Its lines are that record's, at most 40, and none written after the check\. Its `version` and `kind` identify the failed version, `ended_at` its end, `since` the instant the check read its lines from, and `truncated` whether the check's bound cut them\.<br><br>Type: object<br>Required fields: \["version","kind","ended\_at","since","truncated"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>failed\_check/<wbr>properties/<wbr>version | Type: integer |
| /<wbr>properties/<wbr>failed\_check/<wbr>properties/<wbr>kind | Type: string<br>Allowed values: \["deploy","promote","restart"\] |
| /<wbr>properties/<wbr>failed\_check/<wbr>properties/<wbr>ended\_at | Type: \["string","null"\] |
| /<wbr>properties/<wbr>failed\_check/<wbr>properties/<wbr>since | Type: \["string","null"\] |
| /<wbr>properties/<wbr>failed\_check/<wbr>properties/<wbr>truncated | Type: boolean |
| /<wbr>properties/<wbr>environment | Type: string |
| /<wbr>properties/<wbr>entries | Type: array |
| /<wbr>properties/<wbr>entries/<wbr>items | Type: object<br>Required fields: \["at","level","source","message"\] |
| /<wbr>properties/<wbr>entries/<wbr>items/<wbr>properties/<wbr>at | Type: string |
| /<wbr>properties/<wbr>entries/<wbr>items/<wbr>properties/<wbr>level | Type: string |
| /<wbr>properties/<wbr>entries/<wbr>items/<wbr>properties/<wbr>source | Type: string |
| /<wbr>properties/<wbr>entries/<wbr>items/<wbr>properties/<wbr>message | Type: string |
| /<wbr>properties/<wbr>entries/<wbr>items/<wbr>properties/<wbr>fields | Type: object |
| /<wbr>properties/<wbr>waited\_ms | Present where the request carried `wait_seconds`: the time the answer was held, in milliseconds\. On a store source, the answer's `lines` and `entries` come from a fresh read after the wait, whatever ended it\. A `container` answer on a container app merges the store's lines with every line its follows read, and on a pod it carries the followed lines alone\. It carries no `settled`\.<br><br>Type: integer<br>Minimum: 0 |
| /<wbr>properties/<wbr>console\_since | Present on a `container` answer where the environment runs as a pod, from a read that did not follow the console\. It is where the live console the read covered begins: the start of the oldest standing pod's earliest container whose log the cluster keeps\. A line written before it is not in the live console; it can answer only as an ended\-pod line, marked `[pod-ended]`, where its process kept it\. Null where the environment has no pod, and absent on the container grain and on an answer a wait's follow composed\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>page | $ref: \#/shapes/page |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "required": [
      "application"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "Your account's application `id` from `list_applications`, not its name or label."
      },
      "environment": {
        "type": "string",
        "description": "Default production. `local` is the caller computer's stream. Without compute, `container` can return kept failed-check lines or refuse `deploy_in_flight` or `never_deployed`; read the detail for why. `container` with local gives `invalid_request`."
      },
      "since": {
        "type": "string",
        "description": "Inclusive timestamp with a time zone: `YYYY-MM-DDTHH:mm[:ss[.fraction]]`, then `Z` or `±HH:mm`. Fraction has 1–9 digits, T/Z ignore case. Malformed gives `invalid_request`. Default open, except 24 hours back for a container environment's console."
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "maximum": 1000,
        "description": "Newest entries retained, default 100."
      },
      "source": {
        "type": "string",
        "description": "`container`: stdout/stderr. `app`: logging-package records. `egress`: outbound proxy. `harness`: runtime harness. `pool`: functions. Also `platform` and `router`. `all` or absent merges by time. On an all-source read, any of `level`, `field`, `filter`, `contains` or `until` excludes console lines.",
        "enum": [
          "app",
          "platform",
          "router",
          "egress",
          "harness",
          "pool",
          "container",
          "all"
        ]
      },
      "filter": {
        "description": "Connections to hosts declared or undeclared in the manifest's `egress` at the read. Naming `source` selects its page: `egress` reads the proxy's records, `harness` connections made without the proxy. With no source, the returned page may hold neither.",
        "enum": [
          "declared",
          "undeclared"
        ]
      },
      "until": {
        "type": "string",
        "description": "Inclusive end, with `since` syntax and validation. Default open."
      },
      "level": {
        "type": "string",
        "description": "Minimum level: `debug`, `info`, `warn` or `error`. Other values are ignored."
      },
      "contains": {
        "type": "string",
        "description": "Message text. On `container`, case-insensitive over the newest 1000 lines, with indented continuation lines, before `limit`."
      },
      "field": {
        "type": "string",
        "description": "Structured field matched with `value`. Without `value`, any entry with the field. For a response's `x-request-id`, use `request_id` here, its header as `value`, and no `source`. This finds stored records, not console lines."
      },
      "value": {
        "type": [
          "string",
          "number",
          "boolean",
          "null"
        ],
        "description": "JSON-typed equality with `field`, including null. Omitted matches any entry with the field."
      },
      "wait_seconds": {
        "type": "integer",
        "minimum": 1,
        "maximum": 45,
        "description": "Wait for an entry, with `since`. For `container`, the console is followed for at most 40 seconds. Out of range gives `invalid_request`."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "lines"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "reference": {
        "type": "string",
        "pattern": "^[0-9a-f]{10}$",
        "description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call."
      },
      "lines": {
        "type": "array",
        "description": "The answer's lines, oldest first. From a store source each line renders one entry. From `container` a line is `<time> <stream> <text>`: the time the process wrote it, then `stdout` or `stderr` on the container grain, or `-` on the pod grain, whose log gives no stream. On the container grain the lines are ordered by that time; on the pod grain they come pod by pod, the ended pods' lines first (PLD-L0-137). A line from the compute the environment records as previous, the version being replaced, carries `[retiring]` after its stream; a line of the new version never does. On the container grain a line the stopped replica wrote at or after the provider's scale to zero carries `[idle-stop]` there instead, and a `[retiring]` line never carries it; the pod grain marks no idle stop. A read whose window starts after the scale to zero, or one made before the provider's record of the stop arrives, leaves those lines unmarked. On the pod grain an ended-pod line, one of the first and last lines each process of an ended pod wrote, carries `[pod-ended]` after its stream, or after `[retiring]` where it carries both. Ended-pod lines come before the standing pods' lines, read from `since`, or from 24 hours back where it is absent. Where the environment has no compute, no version serves, and the newest version's failed health or smoke check kept lines, `container` returns those lines as the check kept them, at most 40, with no line written after the check.",
        "items": {
          "type": "string"
        }
      },
      "retiring_lines": {
        "type": "integer",
        "minimum": 1,
        "description": "Present only on a `container` answer where at least one of `lines` carries the `[retiring]` mark the platform set: how many do. Those lines are the previous version's, from the compute being replaced, so where this equals the length of `lines` no line returned is the serving version's. A line the application wrote that opens with `[retiring]` is not counted."
      },
      "detail": {
        "type": "string",
        "description": "Present on an empty answer, saying why nothing was found, and on any answer whose window ends within its source's lag of the read, saying the newest records may not have arrived yet. A read of all sources that holds entries also carries it, saying after any lag that it includes the container's console output, as an empty one says; on the `local` stream, which has no console to read, neither says so. Where the read passes `level`, `field`, `filter`, `contains`, or `until`, or its console read was refused, failed, timed out, or found no compute, it says instead that console output is not included and why. Where the entries of a read of all sources or of `router` hold the router's `answered_5xx` record, the detail gives the `container` read and its `since`. That `since` is the earliest such record's instant less its duration and five seconds. The detail also says that the read returns the newest lines after its `since`, so you raise `limit` or add `contains`, and this sentence takes the place of the console sentence. On the pod grain the read is given for a record of the serving version alone, and the sentence adds that an ended pod keeps its first and last lines. Where the records there are of another version, the detail gives that version and no read; where they carry none, it says so and gives no read. On a read of all sources that sentence follows the console sentence. A `container` read carrying `contains` carries it, opening with the lines searched and matched, what the egress filter kept where given, the number returned where `limit` cut them, and, on the container grain, their span. It says where the cut left a match's later frames out. A `container` answer with lines also carries it where the environment is idle now, saying after any lag that the last lines are an idle stop and that the next request starts the application. Where the platform marked a line of the answer `[retiring]`, the detail ends by saying that such lines are the previous version's, unless that sentence would take it past its budget. Where a `container` detail would pass its budget, sentences are left out, in a fixed order, until it fits. The sentence on more instances than a wait followed goes first. Then go the sentences on missing lines, on the delay before lines reach the log store, on an idle environment, and on a replica not running, stopped, or just restarted. The `[retiring]` sentence goes next, and the sentence on how a wait ended goes last. A pod answer says so where a line longer than the 262,144 bytes its read holds was not returned. Idle is the container app's latest revision holding no replica, or the pod's Deployment scaled to zero, and a halted environment is never idle. Under `app`, only what the application writes through the logging package lands there, and standard output and standard error land under `container`. Under `container`, the compute may have scaled to zero, recent lines may still be in the ingestion, `contains` matched none, or `filter` kept none. Under any other source, no entry is in the window, or none matches the read's filters. The lag is a few seconds for the store's entries, up to a minute for the per-minute records under `router`, `egress`, and `harness` and for a container app's console, and none for a pod's console. On the container grain, where the platform has the direct read enabled, a `container` read also reads each running replica's console directly, once and bounded, and its detail says how that read went. Where the direct read kept lines, the detail gives the time from which the newest lines were read from the replica directly, and says a later read may return them again with the log workspace's stamp. The detail says lines may still be in the ingestion where that read reached no replica or did not complete, giving the reason where it failed. Where it did not complete, the sentence on the delay says instead that the log workspace's lines are those it held at the read, and the reason's sentence says a later read adds lines. A reason's word longer than 29 characters is cut to 29 characters, ending with `…`, in the detail, and `reason` carries it whole. It says so too where a replica is not running, stopped, or has just restarted, or where the answer may lack lines. Where none of those holds and the direct read kept no line, the detail says the replicas' newest lines are in this answer. An empty answer then says only that the compute may have scaled to zero and written nothing. Lines still in the ingestion reach the log workspace up to about a minute after the process writes them, so a later read returns them. A `container` read whose `wait_seconds` did not hold says why, unless its budget leaves that sentence out. The causes are the place taken, the platform's waits or follows full, the management API near its limit, the direct read off, or, on the pod grain, no pod running to follow. It also says where more instances run than the three followed. A `container` answer from a failed health check's kept lines opens with what happened and where `read_status` holds the same lines. Its `contains`, `filter`, and `limit` sentences give counts alone and no span, since those lines carry no time."
      },
      "reason": {
        "type": "string",
        "description": "Present only where a `container` read's direct read of the replicas did not complete: the reason's one word, whole at any length, such as `timed_out`, `throttled`, `http_503`, or a network error code. The `detail` gives the same reason, cutting a word longer than 29 characters. On an answer with lines, or one the filter emptied, it also says the log workspace's lines are those it held at the read, unless its budget leaves that sentence out. A reason beside lines, `timed_out` among them, applies to the direct read alone; a later read adds lines. The word comes from the platform's own read of your replicas through the hosting provider, and its cause may not be known. It does not say whether your application is healthy; `read_status` does. A stream that responded with a 5xx status, 501 and 505 aside, was asked once more where the read's bound allowed."
      },
      "failed_check": {
        "type": "object",
        "description": "Present only on a `container` answer where the environment has no compute, no version serves, and the newest version's failed health or smoke check kept a record. Its lines are that record's, at most 40, and none written after the check. Its `version` and `kind` identify the failed version, `ended_at` its end, `since` the instant the check read its lines from, and `truncated` whether the check's bound cut them.",
        "required": [
          "version",
          "kind",
          "ended_at",
          "since",
          "truncated"
        ],
        "properties": {
          "version": {
            "type": "integer"
          },
          "kind": {
            "type": "string",
            "enum": [
              "deploy",
              "promote",
              "restart"
            ]
          },
          "ended_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "since": {
            "type": [
              "string",
              "null"
            ]
          },
          "truncated": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      },
      "environment": {
        "type": "string"
      },
      "entries": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "at",
            "level",
            "source",
            "message"
          ],
          "properties": {
            "at": {
              "type": "string"
            },
            "level": {
              "type": "string"
            },
            "source": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "fields": {
              "type": "object"
            }
          }
        }
      },
      "waited_ms": {
        "type": "integer",
        "minimum": 0,
        "description": "Present where the request carried `wait_seconds`: the time the answer was held, in milliseconds. On a store source, the answer's `lines` and `entries` come from a fresh read after the wait, whatever ended it. A `container` answer on a container app merges the store's lines with every line its follows read, and on a pod it carries the followed lines alone. It carries no `settled`."
      },
      "console_since": {
        "type": [
          "string",
          "null"
        ],
        "description": "Present on a `container` answer where the environment runs as a pod, from a read that did not follow the console. It is where the live console the read covered begins: the start of the oldest standing pod's earliest container whose log the cluster keeps. A line written before it is not in the live console; it can answer only as an ended-pod line, marked `[pod-ended]`, where its process kept it. Null where the environment has no pod, and absent on the container grain and on an answer a wait's follow composed."
      },
      "page": {
        "$ref": "#/shapes/page"
      }
    }
  }
}
```

## Shared contracts

- [Refusals](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy
- [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/)
- [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/)
- [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes)
- [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)
