# Runtime logs and observability

What a project's apps print and the requests they serve, and the totals behind the Observability page.

Source: https://docs.orbits.africa/api/logs

Runtime logs are what a project's deployments write while they run, and its requests, kept for 7 days. Build logs are a deployment's: see [Deployments](https://docs.orbits.africa/api/deployments). See [Runtime logs](https://docs.orbits.africa/observe/runtime-logs) and [Observability](https://docs.orbits.africa/observe/observability).

Endpoints:

- `GET /v1/teams/{team}/projects/{project}/logs`: Runtime logs
- `GET /v1/teams/{team}/projects/{project}/logs/{log}`: One runtime log entry
- `GET /v1/teams/{team}/projects/{project}/observability`: Production's requests, errors and latency

## The runtime log object



- `id` (string, required)
- `at` (string, required): With milliseconds.
- `source` (string, required): One of `requests`, `functions`.
- `level` (string, required): One of `info`, `warning`, `error`.
- `status` (integer or null, required): A request's HTTP status.
- `method` (string or null, required)
- `path` (string or null, required): Without the query string.
- `duration_ms` (integer or null, required): From the edge receiving the request to the last byte of the answer.
- `message` (string or null, required): An output line, without colour codes; at most 8192 characters.
- `stream` (string or null, required): One of `stdout`, `stderr`.
- `request_id` (string or null, required): The edge's ID for a request, also sent to the app as `X-Request-Id`.
- `host` (string or null, required)
- `region` (string, required)
- `deployment` (object or null, required)
  - `id` (string, required)
  - `sha` (string or null, required)
- `headers` (array of array of string, required): Some request headers, as `[name, value]` pairs: user-agent, accept, content-type, referer, and x-forwarded-for masked. Cookies and authorization are never stored.
## Runtime logs

```http
GET /v1/teams/{team}/projects/{project}/logs
```

The Logs page: every request the edge sent to one of the project's deployments (`source: requests`), and every line its deployments printed while running (`source: functions`), newest first. Build logs are on each deployment (`GET .../deployments/{deployment}/logs`). Entries are kept for 7 days.

A request has `status`, `method`, `path` and `duration_ms`, and no `message`. An output line has `message` and `stream`, and null `status`, `method`, `path` and `duration_ms`. Requests and output lines are not linked: an app's output is whatever it printed, whichever request it was serving. Client IP addresses are stored masked (`102.89.x.x`), and query strings are not stored.

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Query parameters:

- `q` (string): Matches a path or message (any case), or exactly a request ID, status or method. A request ID on its own (32 hex characters, as the edge makes them) matches only that request. At most 200 characters.
- `source` (string): One of `requests`, `functions`.
- `level` (string): A request is `error` for 5xx and `warning` for 4xx. An output line is `warning` when it mentions a warning, and `error` when it was written to stderr or mentions an error. One of `info`, `warning`, `error`.
- `status` (string): Requests only; output lines never match. One of `2xx`, `3xx`, `4xx`, `5xx`.
- `range` (string): One of `1h`, `24h`, `7d`. Defaults to `1h`.
- `limit` (integer): From 1 to 500. Defaults to `50`.
- `cursor` (string): `next_cursor` from the previous page.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/logs" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "as_of": "2026-11-10T09:30:00Z",
  "items": [
    {
      "id": "log_019a16dc-3a1f-7c2e-9b1d-2f4e8a6b0c11",
      "at": "2026-11-10T09:30:00Z",
      "source": "requests",
      "level": "info",
      "status": null,
      "method": "GET",
      "path": "/checkout",
      "duration_ms": null,
      "message": null,
      "stream": "stdout",
      "request_id": null,
      "host": "shop.theorbits.app",
      "region": "abj-1",
      "deployment": {
        "id": "log_01jc8x6e4mq2v7r9y3t5b0zp8w",
        "sha": null
      },
      "headers": [
        [
          "headers"
        ]
      ]
    }
  ],
  "total": 1,
  "total_capped": false,
  "next_cursor": null
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
- `503`: A store this endpoint reads is unreachable. Try again shortly.
## One runtime log entry

```http
GET /v1/teams/{team}/projects/{project}/logs/{log}
```

One entry for the Logs inspector, when the one in the URL is not on the current page. 404 once it is older than 7 days.

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `log`: A `log_` id from `GET .../logs`.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/logs/log_01jc8x6e4mq2v7r9y3t5b0zp8w" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "id": "log_019a16dc-3a1f-7c2e-9b1d-2f4e8a6b0c11",
  "at": "2026-11-10T09:30:00Z",
  "source": "requests",
  "level": "info",
  "status": null,
  "method": "GET",
  "path": "/checkout",
  "duration_ms": null,
  "message": null,
  "stream": "stdout",
  "request_id": null,
  "host": "shop.theorbits.app",
  "region": "abj-1",
  "deployment": {
    "id": "log_01jc8x6e4mq2v7r9y3t5b0zp8w",
    "sha": null
  },
  "headers": [
    [
      "headers"
    ]
  ]
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `503`: A store this endpoint reads is unreachable. Try again shortly.
## Production's requests, errors and latency

```http
GET /v1/teams/{team}/projects/{project}/observability
```

The Observability page: production's traffic over a range, from the runtime logs (the edge's requests to the project's production builds, at its address or a build's own). Requests and server errors (5xx) per bucket with p75 and p99 response times, totals with p50, p75 and p99 against the period before, the busiest routes, requests by status class and by region, and the routes for the Route filter. Times are milliseconds from the edge receiving a request to its last byte. Routes group a path's ids (`/products/8412` is `/products/[id]`) and a static folder's files (`/_next/*`). Percentiles are exact. Buckets are 12 x 5 minutes (`1h`), 24 x an hour (`24h`) or 7 x a day (`7d`), on Lagos's clock; the last is the one still filling.

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Query parameters:

- `range` (string): Buckets: 12 x 5 minutes, 12 x 30 minutes (the project overview's health), 24 x an hour, 7 x a day. One of `1h`, `6h`, `24h`, `7d`. Defaults to `24h`.
- `route` (string): A route from `all_routes`. At most 500 characters.
- `status` (string): Narrows everything but `statuses`. One of `2xx`, `3xx`, `4xx`, `5xx`.
- `region` (string): A region code; `abj-1` is the only one with traffic.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/observability" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "as_of": "2026-11-10T09:30:00Z",
  "range": "1h",
  "bucket_seconds": 3600,
  "totals": {
    "requests": 1,
    "errors": 1,
    "p50_ms": 1,
    "p75_ms": 1,
    "p99_ms": 1
  },
  "previous": {
    "requests": 1,
    "errors": 1,
    "p50_ms": 1,
    "p75_ms": 1,
    "p99_ms": 1
  },
  "buckets": [
    {
      "start": "2026-11-10T09:30:00Z",
      "requests": 1,
      "errors": 1,
      "p75_ms": 1,
      "p99_ms": 1
    }
  ],
  "routes": [
    {
      "route": "/products/[id]",
      "requests": 1,
      "errors": 1,
      "p75_ms": 1,
      "p99_ms": 1
    }
  ],
  "statuses": {
    "2xx": 1,
    "3xx": 1,
    "4xx": 1,
    "5xx": 1
  },
  "regions": [
    {
      "region": "abj-1",
      "requests": 1
    }
  ],
  "all_routes": [
    "all-routes"
  ]
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
- `503`: A store this endpoint reads is unreachable. Try again shortly.
