Filter Segments

Save and reuse named filter presets on any list view. Filter segments let your team bookmark common search configurations so they don’t have to rebuild filters from scratch on every visit.

Overview

Filter segments store a named collection of filter predicates scoped to a specific page module and account. Any user on the account can save, browse, and apply segments — but only authenticated users (not API tokens) can manage them.

A segment captures the exact filter state — type, value ID, and display label — mirroring the frontend’s ActiveFilter shape so segments can be hydrated directly into URL params without translation.

1
{
2
  "id": "seg_dev_a1b2c3d4e5f6g7h8",
3
  "module": "subscriptions",
4
  "name": "Active trials — USD",
5
  "filters": [
6
    { "type": "status", "id": "trialing", "label": "Trialing" },
7
    { "type": "currency", "id": "usd", "label": "USD" }
8
  ],
9
  "created_by_user_id": "usr_dev_...",
10
  "created_at": "2024-06-01T10:00:00Z",
11
  "updated_at": "2024-06-01T10:00:00Z"
12
}

Filter predicates

Each segment stores an array of filter predicates — the individual filters that make up the saved view.

The predicate shape mirrors the frontend’s active filter format so segments can be hydrated directly into URL params without translation.

Authentication

Filter segments require user authentication. Requests authenticated with API tokens receive a 403 Forbidden response. This feature is designed for interactive dashboard use, not API integrations.

Listing segments

Retrieve all segments for an account scoped to a module. Results are paginated and searchable by name.

$
GET /api/{account_id}/filter-segments/?module=subscriptions

Query parameters:

See List Filter Segments for the full API reference.

Creating a segment

Save the current filter state as a named segment.

$
POST /api/{account_id}/filter-segments/

1
{
2
  "module": "subscriptions",
3
  "name": "Active trials — USD",
4
  "filters": [
5
    { "type": "status", "id": "trialing", "label": "Trialing" },
6
    { "type": "currency", "id": "usd", "label": "USD" }
7
  ]
8
}

See Create Filter Segment for the full API reference.

Retrieving a segment

Fetch a single segment by ID.

$
GET /api/{account_id}/filter-segments/{segment_id}

Returns a 404 if the segment does not exist or belongs to a different account.

See Get Filter Segment for the full API reference.

Updating a segment

Rename a segment, update its filters, or reassign it to a different module. All fields are optional — only the fields you provide are updated.

$
PATCH /api/{account_id}/filter-segments/{segment_id}

1
{
2
  "name": "Active trials — EUR",
3
  "filters": [
4
    { "type": "status", "id": "trialing", "label": "Trialing" },
5
    { "type": "currency", "id": "eur", "label": "EUR" }
6
  ]
7
}

Returns a 400 if no fields are provided. Returns a 404 if the segment does not exist.

See Update Filter Segment for the full API reference.

Deleting a segment

Remove a segment permanently. Returns 204 No Content on success.

$
DELETE /api/{account_id}/filter-segments/{segment_id}

Returns a 404 if the segment does not exist.

See Delete Filter Segment for the full API reference.

Limits