> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.v2.rasen.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.v2.rasen.ai/_mcp/server.

# Filters and limits

## GET filters

Repeat a query parameter to pass several values:

```bash
curl -sS "$RASEN_API_BASE/calls?agent_id=agent_a&agent_id=agent_b&terminal=true" \
  -H "Authorization: Bearer $RASEN_API_KEY"
```

* Values of one field are combined with OR; different fields are combined with AND.

* At most **100** values in total across the ID filters of one request.

* An empty or blank value is refused, never read as "no filter". Omit the parameter for no filter.
  The one exception is `metadata_value`: a call's metadata value can be empty, so `metadata_value=`
  (GET) or `"metadata_value": [""]` (POST) finds the calls that stored an empty value.

* An unknown or inaccessible ID yields no rows. It does not reveal whether the resource exists.

## POST search and query

For larger ID sets, `POST /calls/search` and `POST /usage/query` take the same filter names in a
JSON body and answer the same page as their GET forms:

```bash
curl -sS -X POST "$RASEN_API_BASE/calls/search" \
  -H "Authorization: Bearer $RASEN_API_KEY" -H "Content-Type: application/json" \
  -d '{"filter": {"call_id": ["call_…", "call_…"], "extraction_state": ["ready"]}, "limit": 200}'
```

| Limit                            | Value                   |
| -------------------------------- | ----------------------- |
| Body size                        | 131,072 bytes (128 KiB) |
| ID and metadata values, in total | 1000                    |
| Values per state list            | 16                      |
| Usage component values           | 32                      |
| Page size                        | 1 to 200, default 50    |

The byte limit can bind before the value limit when values are very long. A body over the limit
answers `413 payload_too_large`.

These two operations are reads: they have no effect, take no `Idempotency-Key`, count as reads for
rate limits, and put the cursor in the body. They never expand transcripts, results or variables.
An explicit empty array in the filter is refused.

## Date ranges

Call and usage lists take `start` (inclusive) and `end` (exclusive) as UTC timestamps. A range
covers at most 93 days, and the default is the trailing 30 days.

## Limits only grow

After the first external release, these limits can only be raised.