# GraphQL API Examples

This section provides practical examples for querying Retarus GraphQL APIs. Each example demonstrates real-world usage scenarios with complete query syntax, variable definitions, and sample responses.

## Prerequisites

To run the examples below, you must have already obtained an active access token. You’ll include this token with every API call.

For how to obtain and refresh your token, see the [Authentication](/common/graphql-authentication) section.

## Common query structure

All Retarus GraphQL queries follow a consistent pattern:

- **Query**  GraphQL document defining the operation, the fields to fetch, and required variables.
- **Variables**  JSON object whose keys match the declared variables (e.g., customer ID, date range, filters).
- **Response**  JSON with data and optional errors.


## Common parameters

These parameters are used across all service queries:

| **Parameter** | **Type** | **Description** | **Example** |
|  --- | --- | --- | --- |
| `customerId` | String! | Your Retarus customer account identifier | `"99999"` |
| `datePeriod` | DatePeriod! | Time range with UTC timestamps | `{"fromIncluded": "2025-06-04T08:00:00.000Z"}`  `{"toExcluded": "2025-06-04T08:54:00.000Z"}` |
| `pageIndex` | Int | Zero-based page number for pagination | `0` |
| `pageSize` | Int | Maximum records to return per page (max 10,000) | `3` |
| `sort` | SortDirection | Sort direction for results | `"ASC"` or `"DESC"` |
| `filter` | *Service-specific* | Optional column filters that narrow results (see [Filtering](#filtering)) | `{"statusName": {"values": ["OK"]}}` |


> **Enum note**: In the query document, enums are unquoted (e.g., `ASC`). In variables JSON, pass them as strings (e.g., `{ "sort": "ASC"` }).


## Filtering

Most reports accept an optional `filter` argument that narrows results to matching records. The filter type is service-specific (for example, `FaxOutColumnUdrFilters` or `SmsInColumnUdrFilters`), but every filterable column uses the same `ColumnFilter` input:

| **Field** | **Logic** | **Description** |
|  --- | --- | --- |
| `values` | OR | Include only records whose column matches **any** of the listed values. |
| `notValues` | AND NOT | Exclude records whose column matches **any** of the listed values. |


You can set `values`, `notValues`, or both on a column, and filter on several columns at once. Within a single column, `values` are combined with OR and `notValues` with AND NOT; separate columns are combined with AND.

For example, the following `filter` value keeps only records whose `statusName` is `OK`, while excluding two billing codes:

```json
{
  "statusName": { "values": ["OK"] },
  "jobBillingCode": { "notValues": ["ITS065", "ITS099"] }
}
```

> **Note**  `notValues` enables AND NOT filtering. Combine it with `values` to include a set of values and subtract specific exceptions in a single query.


## Common response fields

All service responses include these pagination fields:

| **Field** | **Description** | **Example** |
|  --- | --- | --- |
| `pageIndex` | Current page number | `0` |
| `pageSize` | Requested page size | `3` |
| `hasMoreElements` | Whether more pages are available | `true` |


## Date period format

All date periods use ISO 8601 UTC format:

- `fromIncluded`  Start time (inclusive) - `"2025-06-04T08:00:00.000Z"`
- `toExcluded`  End time (exclusive) - `"2025-06-04T08:54:00.000Z"`


**Data retention limits**

- Maximum query duration: 45 days per request
- Maximum history: within 90 days of the current UTC time


## Product-specific examples

Fax Outbound Example
Retrieve outbound fax transmission records

Fax Inbound Example
Access inbound fax reception records

SMS Inbound Example
Track SMS senders, keywords, and message content

SMS Outbound Example
Review outbound SMS transmission records

Email Delivery Example
Query transactional email usage detail records

Email Event Example
Check transactional email engagement event records