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

# Search function logs

> Page through the log lines your GenAI functions wrote, newest first.

Returns the log lines written by the GenAI functions of an account, one entry per line, with the event label and the span the function ran in. Filter by conversation, function, level, environment, error type, whole-word text, or the exact span. The raw log line and its payload are never returned. See the [overview](https://docs.poly.ai/api-reference/traces/introduction.md#function-logs) for how lines link to spans.

## Request

### Headers

**X-API-KEY** `string` *required*

Account API key with read access to conversations.

### Body

**project\_id** `string`

Restrict to one agent. Omit to search the whole account.

**conversation\_id** `string`

Matches the conversation ID or the call SID.

**function\_names** `string[]`

Function (tool) names, up to 20.

**levels** `string[]`

`debug`, `info`, `warning`, `error`, `critical`.

**client\_envs** `string[]`

Environments: `test`, `sandbox`, `pre-release`, `live`, `scenarios`. `pre-release` is the Staging environment.

**error\_types** `string[]`

Exception classes on failure lines, for example `KeyError`, up to 20.

**text** `object`

Whole-word, case-insensitive terms matched on the event label: `{ "all": [...], "any": [...], "none": [...] }`, up to 10 terms each. `api request` finds `API request error`; `api req` does not.

**trace\_id** `string`

Trace ID of the function-execution span.

**span\_id** `string`

Span ID of the function-execution span. Returns exactly the lines that one execution wrote.

**turn\_index** `integer`

0-based turn the function call belongs to. Must be an integer.

**from** `datetime`

Inclusive window start. Defaults to 24 hours before `to`. The window may span at most 30 days.

**to** `datetime`

Exclusive window end. Defaults to now. The response echoes the value used; pass it back when paging so new lines do not shift the pages.

**order** `string` (default: desc)

`desc` (newest first) or `asc`.

**limit** `integer` (default: 50)

Lines per page, 1–100.

**offset** `integer` (default: 0)

Lines to skip, 0–1000.

## Response

**logs** `object[]`

One entry per log line.

**properties**

**timestamp** `datetime`

**level** `string`

**project\_id** `string`

**client\_env** `string`

**function\_name** `string`

**conversation\_id** `string`

**call\_sid** `string`

**event** `string`

The event label the function logged, for example `API request error`.

**error\_type** `string`

Exception class on a failure line, for example `KeyError`. Empty otherwise.

**trace\_id** `string`

Trace ID of the function-execution span. Empty when the line is not linked.

**span\_id** `string`

Span ID of the function-execution span. Empty when the line is not linked.

**turn\_index** `string`

0-based turn the call belongs to, as a string. Empty when unknown.

**from** `datetime`

Window start actually used.

**to** `datetime`

Window end actually used.

**limit** `integer`

**offset** `integer`

**has\_more** `boolean`

## Examples

### Errors from one function in the last 24 hours

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.us.poly.ai/api/v1/traces/logs/search \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "PROJECT-V258TF29",
    "function_names": ["send_sms"],
    "levels": ["error"],
    "limit": 2
  }'
```

```json Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "logs": [
    {
      "timestamp": "2026-10-26T18:22:36.175000+00:00",
      "level": "error",
      "project_id": "PROJECT-V258TF29",
      "client_env": "live",
      "function_name": "send_sms",
      "conversation_id": "CA3f2c1e9d6b7a4f8e9c0d1b2a3c4d5e6f",
      "call_sid": "CA3f2c1e9d6b7a4f8e9c0d1b2a3c4d5e6f",
      "event": "SMS failed to send",
      "error_type": "",
      "trace_id": "183208fafb304cebf5e07c90f7b48f0f",
      "span_id": "8cff57c6d5aaa768",
      "turn_index": "10"
    }
  ],
  "from": "2026-10-26T13:57:43.353614+00:00",
  "to": "2026-10-27T13:57:43.353614+00:00",
  "limit": 2,
  "offset": 0,
  "has_more": true
}
```

### Everything one execution wrote

Take `span_id` from a search result, or from a span search, and pass it back:

```json Request theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "project_id": "PROJECT-V258TF29",
  "span_id": "8cff57c6d5aaa768",
  "order": "asc"
}
```

### Uncaught exceptions in a conversation

```json Request theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "project_id": "PROJECT-V258TF29",
  "conversation_id": "CA3f2c1e9d6b7a4f8e9c0d1b2a3c4d5e6f",
  "error_types": ["KeyError", "TimeoutError"],
  "from": "2026-10-20T00:00:00Z",
  "to": "2026-10-27T00:00:00Z"
}
```

## Errors

| Status | Meaning |
| - | - |
| `400` | The window is empty or exceeds 30 days. |
| `401` | Missing or invalid API key. |
| `403` | The key cannot read conversations. |
| `422` | A value is outside its enum or range, or `turn_index` is not an integer. |
| `502` | The log backend did not answer. |