---
title: "Requests and filters | Trellus Call Data API"
description: "Request parameters, microsecond date ranges, AND/OR filter groups, operators, array paths and copyable filter recipes for the Trellus Call Data API."
source: "https://www.trellus.ai/developers/api/requests"
note: "Text-only copy of the page for AI assistants and agents. Link to the source address, not this file."
site_summary: "https://www.trellus.ai/llms.txt"
---

# Requests and filters

Body parameters, microsecond date ranges, filter groups, operators and array paths.

## Request parameters

List and metrics requests use `Content-Type: application/json`. Put parameters in the POST body. The same parameters are listed per endpoint on [List calls and transcripts](https://www.trellus.ai/developers/api/list-calls) and [Count calls and sum durations](https://www.trellus.ai/developers/api/metrics).

List and metrics request parameters

| Parameter | Type / requirement | Meaning |
| --- | --- | --- |
| `start` | integer Required | Inclusive UTC range start in Unix microseconds. Use Date.parse(ISO_WITH_TIMEZONE) \* 1000 in JavaScript. |
| `end` | integer Optional | Exclusive UTC range end in Unix microseconds. Defaults to now. |
| `team_id` | string Optional | One permitted team per request; defaults to the key owner’s team. This does not expand access. |
| `cnf` | Filter[][] Optional | AND of OR filter groups. Defaults to []. Do not use an empty inner group. |
| `select` | string[] Required for lists | Exact reporting column paths. Response cell i corresponds to select[i]. |
| `limit` | integer Optional for lists | Default 50; minimum 1 and maximum 1000. A row cap, not a page size with a continuation token. |
| `selects` | Aggregate[] Required for metrics | Ordered count or sum definitions. Each select can include cnf, column_name, or both. Empty {} is invalid. |
| `group_by` | object Optional for metrics | Reporting column_name. Prepends the group value to each result row. |

## Date and time units

**Two timestamp units:** request `start` and `end` are Unix microseconds. Returned `started_at` and values in a `started_at` filter are Unix seconds. Duration and transcript offsets are also seconds. The date range includes its start and excludes its end.

Convert UTC dates and list timestamps

```javascript
const start = Date.parse("2026-10-01T00:00:00Z") * 1000;
const end = Date.parse("2026-10-08T00:00:00Z") * 1000;
// A returned list started_at value uses seconds:
const startedAt = new Date(started_at * 1000);
```

## Filters

`cnf` is an AND list of OR groups: every outer group must match, and at least one condition inside each group must match. An empty outer list adds no extra filter. Avoid empty inner groups.

Each condition needs `column_name`, `operator` and `value_safe`. Use actual booleans, numbers or strings. `IN` and `NIN` take arrays. Recognized enum fields accept their names or numeric values; byte values use base64. `user_log.source` is a numeric field for list results and filters: use the documented numeric codes, not their explanatory labels.

Calls from two reps, with an outcome or 30 live seconds

```json
{
  "cnf": [
    [
      {
        "column_name": "conversation_type",
        "operator": "EQ",
        "value_safe": 1
      }
    ],
    [
      {
        "column_name": "resource_id",
        "operator": "IN",
        "value_safe": [
          "REP_ID_ONE",
          "REP_ID_TWO"
        ]
      }
    ],
    [
      {
        "column_name": "user_log.disposition",
        "operator": "EQ",
        "value_safe": "YOUR_INTERESTED_OPTION"
      },
      {
        "column_name": "dial_metric.live_duration",
        "operator": "GE",
        "value_safe": 30
      }
    ]
  ]
}
```

## Operators

Supported filter operators

| Operator | Meaning |
| --- | --- |
| `EQ` | Equal to the typed value. |
| `NEQ` | Not equal to the typed value. |
| `GT` | Greater than. |
| `GE` | Greater than or equal to. |
| `LT` | Less than. |
| `LE` | Less than or equal to. |
| `IN` | One of the values in the value_safe array. |
| `NIN` | Not in the value_safe array. |
| `REGEX` | Search a string with the backend regular-expression engine; look-around and backreferences are not supported. |

## Arrays and custom fields

Select an array as a whole, use a concrete path such as `agents.[0].agent_id`, or project members with `agents.[*].agent_id`. A filter containing `[*]` requires `reducer: "ANY"` or `reducer: "ALL"`. Do not add a reducer to a filter without `[*]`; select projections do not use reducers.

`customer_data.custom_fields` is JSON text in list results. Parse it before reading keys. Captured keys vary by account and source; there is no guaranteed standard contact email column.

Every selectable path is in the [field reference](https://www.trellus.ai/developers/api/fields).

## Filter recipes

Replace sample rep IDs and outcome labels with the values returned by `/visible` and `/bootstrap`. `agent_joined: false` alone is not a universal definition of a missed call: combine it with call type and inbound filters for that analysis.

Inbound calls

```json
[{ "column_name": "dial_metric.is_inbound", "operator": "EQ", "value_safe": true }]
```

Longer calls

```json
[{ "column_name": "duration", "operator": "GE", "value_safe": 300 }]
```

Human connected examples

```json
[{ "column_name": "dial_metric.live_duration", "operator": "GE", "value_safe": 30 }]
```

No agent joined

```json
[{ "column_name": "agent_joined", "operator": "EQ", "value_safe": false }]
```

Specific rep/resource

```json
[{ "column_name": "resource_id", "operator": "EQ", "value_safe": "USER_ID" }]
```

Resolved user name

```json
[{ "column_name": "resource_id", "operator": "EQ", "value_safe": "USER_ID_FROM_BOOTSTRAP" }]
```

Disposition

```json
[{ "column_name": "user_log.disposition", "operator": "IN", "value_safe": ["Interested", "Demo booked"] }]
```

Purpose

```json
[{ "column_name": "user_log.purpose", "operator": "EQ", "value_safe": "Follow up" }]
```