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

# Pagination and Filtering

> Page through API results and filter run exports

List endpoints use cursor pagination. Pass `limit` to choose a page size, then pass `pagination.next_cursor` as `cursor` to request the next page.

## Pagination

Runs default to `limit=50` and are capped at `100`.

Tools, agents, guidelines, guardrails, and runbooks default to `limit=100` and are capped at `200`.

```bash theme={null}
curl "https://app.useduckie.ai/api/v1/runs?limit=50" \
  -H "Authorization: Bearer dk_live_your_api_key"
```

```json theme={null}
{
  "data": [],
  "pagination": {
    "limit": 50,
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNi0wM1QwMDowMDowMC4wMDBaIiwiaWQiOiIwMDAwMDAwMC0wMDAwLTQwMDAtODAwMC0wMDAwMDAwMDAwMDAifQ",
    "has_more": true
  }
}
```

Use the returned cursor as an opaque string:

```bash theme={null}
curl "https://app.useduckie.ai/api/v1/runs?limit=50&cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wNi0wM1QwMDowMDowMC4wMDBaIiwiaWQiOiIwMDAwMDAwMC0wMDAwLTQwMDAtODAwMC0wMDAwMDAwMDAwMDAifQ" \
  -H "Authorization: Bearer dk_live_your_api_key"
```

## Runs Filters

`GET /api/v1/runs` supports these filters:

| Filter            | Behavior                                                               |
| ----------------- | ---------------------------------------------------------------------- |
| `created_after`   | ISO timestamp lower bound                                              |
| `created_before`  | ISO timestamp upper bound                                              |
| `status`          | One or more of `completed`, `running`, `failed`, `cancelled`, `paused` |
| `ticket_id`       | Exact source ticket or conversation ID                                 |
| `agent_id`        | Agent UUID                                                             |
| `source`          | Exact source match                                                     |
| `resolution_type` | One or more of `deflected`, `resolved`, `escalated`, `pending`         |
| `duration[eq]`    | Exact duration in seconds                                              |
| `duration[gt]`    | Duration greater than a number of seconds                              |
| `duration[gte]`   | Duration greater than or equal to a number of seconds                  |
| `duration[lt]`    | Duration less than a number of seconds                                 |
| `duration[lte]`   | Duration less than or equal to a number of seconds                     |
| `tool_name`       | Exact recorded tool name from a tool-call step                         |
| `search`          | Text search over ticket title, ticket ID, and agent name               |
| `metadata.<key>`  | Metadata key/value filter                                              |

Repeat `status`, `ticket_id`, `agent_id`, `source`, `resolution_type`, or `tool_name` to OR together multiple values.

```bash theme={null}
curl "https://app.useduckie.ai/api/v1/runs?status=completed&status=failed&duration[gte]=60&duration[lt]=300" \
  -H "Authorization: Bearer dk_live_your_api_key"
```

## Tool-Name Filters

Run tool filters use the recorded `run_steps.tool_name` value for steps where `type` is `tool_call`. Display labels are not accepted as filter values.

Use the tool-options endpoint to discover valid historical values:

```bash theme={null}
curl "https://app.useduckie.ai/api/v1/runs/tool-options" \
  -H "Authorization: Bearer dk_live_your_api_key"
```

```json theme={null}
{
  "data": [
    {
      "tool_name": "knowledge_search",
      "display_name": "Knowledge Search",
      "run_count": 42
    }
  ]
}
```

## Tools Filters

`GET /api/v1/tools` supports these filters:

| Filter              | Behavior                                                                 |
| ------------------- | ------------------------------------------------------------------------ |
| `type`              | One or more of `duckie_tool`, `app_tool`, `custom_tool`, `mcp_tool`      |
| `search`            | Search tool name, description, app integration name, and MCP server name |
| `is_write_action`   | `true` or `false`                                                        |
| `requires_approval` | `true` or `false`                                                        |
| `integration_id`    | Match app tools for one integration                                      |
| `mcp_server_id`     | Match MCP tools for one server UUID                                      |

```bash theme={null}
curl "https://app.useduckie.ai/api/v1/tools?type=custom_tool&requires_approval=true" \
  -H "Authorization: Bearer dk_live_your_api_key"
```

## Guardrail Filters

`GET /api/v1/guardrails` accepts `type=escalation` or `type=restriction`.