# Logs

> Log search and live tail.

Log search and live tail.

| Operation | Method and path |
| --- | --- |
| [Search logs](#search-logs) | `GET /v1/projects/{project}/logs` |
| [Live tail (Server-Sent Events)](#live-tail-server-sent-events) | `GET /v1/projects/{project}/logs/tail` |

## Search logs

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

`q` is plain text or LogsQL. Tenant filters are applied server-side. Lines are untrusted customer content.

- **Operation:** `queryLogs`
- **Scopes:** `logs:read`
- **CLI:** `guv logs`
- **Paginated:** `?limit=` and `?cursor=`

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `project` * | path | string | Project id (`prj_…`) or slug (resolved in the `Guv-Workspace` workspace, or the caller's default). |
| `environment` | query | string |  |
| `service` | query | string |  |
| `deployment` | query | string |  |
| `source` | query | `build`, `deploy`, `runtime`, `http` |  |
| `level` | query | `debug`, `info`, `warn`, `error`, `fatal` | Minimum level. |
| `q` | query | string |  |
| `since` | query | string | RFC 3339 time or a duration like 10m. |
| `until` | query | string (date-time) |  |
| `direction` | query | `backward`, `forward` |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| `200` OK | OK. | [LogQueryResult](/docs/api/objects/log-query-result/) |

**Errors:** `400`, `401`, `403`, `404`, `429`, `500`, as [problem+json](/errors/) with a stable `code`.

**Example**

```bash
curl https://api.guv.dev/v1/projects/shopfront/logs \
  -H "Authorization: Bearer $GUV_TOKEN"
```

**Example response**

```json
{
  "lines": [
    {
      "id": "lg_9f8e7d6c5b",
      "timestamp": "2026-10-23T14:04:02.123Z",
      "source": "runtime",
      "level": "error",
      "message": "TypeError: Cannot read properties of undefined (reading 'id')",
      "service": {
        "id": "svc_01jbx2m9k7q4r8t5v6w3y0z1sv",
        "name": "web"
      },
      "environment": "production",
      "deployment_id": "dep_01jbx2m9k7q4r8t5v6w3y0z1dp",
      "replica": "web-1",
      "http": null,
      "attributes": {},
      "redacted": false
    }
  ],
  "next_cursor": "string",
  "has_more": false,
  "query": "string",
  "dropped_lines": 1
}
```

## Live tail (Server-Sent Events)

```http
GET /v1/projects/{project}/logs/tail
```

Events `log` (LogLine), `dropped` ({count}) and `heartbeat` every 15 s. Bounded to 1 hour per connection.

- **Operation:** `tailLogs`
- **Scopes:** `logs:read`
- **CLI:** `guv logs -f`

**Parameters**

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `project` * | path | string | Project id (`prj_…`) or slug (resolved in the `Guv-Workspace` workspace, or the caller's default). |
| `environment` | query | string |  |
| `service` | query | string |  |
| `level` | query | `debug`, `info`, `warn`, `error`, `fatal` |  |
| `q` | query | string |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| `200` OK | Server-Sent Events stream. Each event's `data` is a JSON LogLine. | string |

**Errors:** `400`, `401`, `403`, `404`, `429`, `500`, as [problem+json](/errors/) with a stable `code`.

**Example**

```bash
curl https://api.guv.dev/v1/projects/shopfront/logs/tail \
  -H "Authorization: Bearer $GUV_TOKEN"
```

**Example response**

```json
"string"
```