> ## Documentation Index
> Fetch the complete documentation index at: https://docs.catchthegoodones.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List segments

> List the reusable filter sets you've authored

Lists the segments (reusable filter sets) owned by the user. Code-side these are `segments`; user-facing we call them "segments".

To create a new segment, see [POST /api/v2/segments](/api-reference/create-segment). To author + attach to a stream in one shot, see [POST /api/v2/streams](/api-reference/create-stream) (the `pairs` field accepts inline segment objects).

## Query parameters

| Name              | Type    | Description                              |
| ----------------- | ------- | ---------------------------------------- |
| `excludeArchived` | boolean | Default `true` - hides archived segments |

## Response

```json theme={null}
{
  "segments": [
    {
      "id": 12,
      "userFacingId": "seg_12",
      "name": null,
      "description": "AI founders building developer tools",
      "genderValues": [],
      "appliedSearchFilters": { "job_role": ["Founder", "CEO"] },
      "followerCountTiers": [],
      "linkedStreamCount": 2,
      "createdAt": "2026-06-01T10:00:00Z",
      "updatedAt": "2026-06-01T10:00:00Z"
    }
  ]
}
```

## Notes

Editing a segment's filters in place is intentionally NOT exposed on the public API (mutating a segment affects classification across every stream that references it - too easy to get wrong from an integration). Workflow:

1. `POST /api/v2/segments` to create a new segment with the desired filters
2. `PATCH /api/v2/streams/{id}` to swap the affected streams' pairs to use the new segment

## Auth

Bearer or session cookie.