> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timberlogs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Logs

> Retrieve logs from Timberlogs with filtering and pagination.

## List Logs

**GET** `/v1/logs`

### Query Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `limit` | number | 100 | Number of logs to return (max 1000) |
| `offset` | number | 0 | Number of logs to skip |
| `level` | string | - | Filter by log level |
| `source` | string | - | Filter by source |
| `environment` | string | - | Filter by environment |
| `dataset` | string | - | Filter by dataset |
| `userId` | string | - | Filter by user ID |
| `sessionId` | string | - | Filter by session ID |
| `flowId` | string | - | Filter by flow ID |
| `from` | number | - | Start timestamp (Unix ms) |
| `to` | number | - | End timestamp (Unix ms) |

### Response

```json theme={null}
{
  "logs": [
    {
      "id": "log_abc123",
      "timestamp": 1704067200000,
      "level": "info",
      "message": "User signed in",
      "source": "api-server",
      "environment": "production",
      "userId": "user_123",
      "sessionId": "sess_abc",
      "data": {"method": "oauth"},
      "tags": ["auth"]
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "count": 50,
    "hasMore": false
  }
}
```

### Examples

**Basic query:**

```bash theme={null}
curl -X GET "https://timberlogs-ingest.enaboapps.workers.dev/v1/logs" \
  -H "Authorization: Bearer tb_live_xxxxxxxxxxxxx"
```

**Filter by level:**

```bash theme={null}
curl -X GET "https://timberlogs-ingest.enaboapps.workers.dev/v1/logs?level=error" \
  -H "Authorization: Bearer tb_live_xxxxxxxxxxxxx"
```

**Filter by source and environment:**

```bash theme={null}
curl -X GET "https://timberlogs-ingest.enaboapps.workers.dev/v1/logs?source=api-server&environment=production" \
  -H "Authorization: Bearer tb_live_xxxxxxxxxxxxx"
```

**Filter by time range:**

```bash theme={null}
curl -X GET "https://timberlogs-ingest.enaboapps.workers.dev/v1/logs?from=1704067200000&to=1704153600000" \
  -H "Authorization: Bearer tb_live_xxxxxxxxxxxxx"
```

**Filter by user:**

```bash theme={null}
curl -X GET "https://timberlogs-ingest.enaboapps.workers.dev/v1/logs?userId=user_123" \
  -H "Authorization: Bearer tb_live_xxxxxxxxxxxxx"
```

**Filter by flow:**

```bash theme={null}
curl -X GET "https://timberlogs-ingest.enaboapps.workers.dev/v1/logs?flowId=checkout-a1b2c3d4" \
  -H "Authorization: Bearer tb_live_xxxxxxxxxxxxx"
```

**Pagination:**

```bash theme={null}
# First page
curl -X GET "https://timberlogs-ingest.enaboapps.workers.dev/v1/logs?limit=50" \
  -H "Authorization: Bearer tb_live_xxxxxxxxxxxxx"

# Second page
curl -X GET "https://timberlogs-ingest.enaboapps.workers.dev/v1/logs?limit=50&offset=50" \
  -H "Authorization: Bearer tb_live_xxxxxxxxxxxxx"
```

## Get Single Log

**GET** `/v1/logs/:id`

Retrieve a single log by its ID.

### Response

```json theme={null}
{
  "log": {
    "id": "log_abc123",
    "timestamp": 1704067200000,
    "level": "info",
    "message": "User signed in",
    "source": "api-server",
    "environment": "production",
    "userId": "user_123",
    "sessionId": "sess_abc",
    "requestId": "req_xyz",
    "data": {"method": "oauth"},
    "tags": ["auth"],
    "flowId": "login-x1y2z3",
    "stepIndex": 0
  }
}
```

### Error Responses

**401 Unauthorized** - Invalid or missing API key

```json theme={null}
{
  "error": "Invalid API key"
}
```

**How to resolve:** Ensure your `Authorization` or `X-API-Key` header is included and valid. See [Authentication](/api-reference/authentication) for details.

**404 Not Found** - Log not found

```json theme={null}
{
  "error": "Log not found"
}
```

**How to resolve:** The log ID doesn't exist or belongs to a different workspace. Verify the ID and ensure your API key has access to the correct workspace.

### Example

```bash theme={null}
curl -X GET "https://timberlogs-ingest.enaboapps.workers.dev/v1/logs/log_abc123" \
  -H "Authorization: Bearer tb_live_xxxxxxxxxxxxx"
```

## Log Object

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique log identifier |
| `timestamp` | number | Unix timestamp in milliseconds |
| `level` | string | Log level: `debug`, `info`, `warn`, `error` |
| `message` | string | Log message |
| `source` | string | Application/service name |
| `environment` | string | Environment name |
| `dataset` | string | Dataset name |
| `version` | string | Application version |
| `userId` | string | User identifier |
| `sessionId` | string | Session identifier |
| `requestId` | string | Request identifier |
| `data` | object | Additional structured data |
| `errorName` | string | Error class/name |
| `errorStack` | string | Error stack trace |
| `tags` | string\[] | Array of tags |
| `country` | string | Country code (auto-detected) |
| `ipAddress` | string | Client IP address |
| `flowId` | string | Flow identifier |
| `stepIndex` | number | Step index within flow |

## Pagination

The API uses offset-based pagination:

* `limit` - Number of items per page (default: 100, max: 1000)
* `offset` - Number of items to skip
* `hasMore` - Boolean indicating if more results exist

To iterate through all logs:

```typescript theme={null}
let offset = 0
const limit = 100
let hasMore = true

while (hasMore) {
  const response = await fetch(
    `https://timberlogs-ingest.enaboapps.workers.dev/v1/logs?limit=${limit}&offset=${offset}`,
    { headers: { Authorization: `Bearer ${apiKey}` } }
  )
  const data = await response.json()

  // Process data.logs
  console.log(`Fetched ${data.logs.length} logs`)

  hasMore = data.pagination.hasMore
  offset += limit
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.