---
title: "Reading data"
description: "Select fields, filter and sort results, paginate, and include related resources."
lastModified: "2026-08-21"
---

Every readable resource supports both a collection and an individual record request:

```
GET /api/core/organizations/{organization_id}/{resource}
GET /api/core/organizations/{organization_id}/{resource}/{id}

GET /api/core/organizations/{organization_id}/events/{event_id}/{resource}
GET /api/core/organizations/{organization_id}/events/{event_id}/{resource}/{id}
```

## Selecting response fields

Response fields are selected by the token scope, not by each API call. There is no caller-controlled `fields[...]` parameter. To receive another field, ask an organization administrator to add it to **Readable fields** for that resource's scope.

This matters when troubleshooting apparently incomplete responses: a valid response containing only `id` is possible when no other read fields are selected.

## Filters

Filters are ordinary query parameters and use underscored names:

```shell
curl --get \
  --url "https://api.brella.io/api/core/organizations/30/events/319986/leads" \
  --header "Accept: application/vnd.brella.v4+json" \
  --header "Brella-API-Access-Token: YOUR_TOKEN" \
  --data-urlencode "sponsor_id=103705" \
  --data-urlencode "created_from=2026-08-01T00:00:00Z" \
  --data-urlencode "created_to=2026-08-31T23:59:59Z"
```

Only filters selected in the token scope are applied. Other resource-specific query parameters are ignored. The one exception is a filter declared as required by the resource: `comparison_event_ids` for organization event benchmarks is always required and applied.

Filter behavior:

- equality filters match the supplied value;  
- `_from` filters are inclusive lower bounds (`>=`);  
- `_to` filters are inclusive upper bounds (`<=`);  
- values may be scalars or arrays of scalar values;  
- enum filters reject invalid enum values with `400`;  
- nested objects are not valid filter values; and  
- an unknown value handled by a custom filter may produce an empty result rather than an error, as noted in the relevant resource.

For multiple values, use repeated array parameters where supported, or the comma-separated format explicitly documented for benchmark comparison IDs:

```
?status[]=invited&status[]=joined
?comparison_event_ids=101,102,103
```

## Sorting

Only `abuse-reports` currently declares named sorts:

```
?sort=latest_instance
?sort=report_count
```

Both are descending and use record ID as a stable tie-breaker. An unrecognized sort value leaves the normal ascending-ID order in place.

## Pagination

Collection endpoints are paginated in ascending record-ID order unless a declared sort is used.

```
?page[number]=2&page[size]=50
```

- Default page size: `30 [may change prior to release]`  
- Maximum page size: `100`  
- Values at or below zero use the default page size.

Pagination metadata is returned at the document level:

```json
{
  "meta": {
    "total_count": 245,
    "total_pages": 5,
    "current_page": 2
  }
}
```

## Including related resources/ associations

Use a comma-separated `include` query parameter. The requested names are the underscored association names listed in this reference and must also be enabled in the scope:

```
?include=registrant,created_by_registrant,custom_fields
```

Without `include`, configured relationships are still represented by JSON:API linkage, but the related objects are not placed in the top-level `included` array. Unknown, unconfigured, and disallowed include names are ignored.

An association can have a different response name. For example, request `include=created_by_registrant`; the response relationship is `created-by-registrant`. Each included object contains `id` plus the association fields selected in the scope.

Nullable relationships are valid. For example, a lead can have `created-by-registrant.data: null` when it was created without a creator registrant, even if that association and all of its fields are correctly configured.