> ## 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 leads

> Cross-stream lead extraction for Zapier-style polling

Returns leads across every campaign owned by the user. Useful for Zapier-style polling. For campaign-scoped extraction use [GET /api/v2/streams/{id}/leads](/api-reference/stream-leads).

## Query parameters

| Name        | Type     | Description                                                                                   |
| ----------- | -------- | --------------------------------------------------------------------------------------------- |
| `streamId`  | number   | Scope to one campaign                                                                         |
| `segmentId` | number   | Scope to one segment                                                                          |
| `accountId` | number   | Scope to one source account                                                                   |
| `lifecycle` | enum     | `"new"` or `"exported"`                                                                       |
| `since`     | ISO 8601 | Leads discovered after this timestamp                                                         |
| `groupBy`   | enum     | `"stream"` returns `{groups: [{streamId, streamName, leads: [...]}]}` instead of a flat array |

## Response (flat)

```json theme={null}
{
  "data": [
    {
      "id": 1234,
      "trackedAccount": { "id": 7, "xHandle": "yongfook" },
      "profile": { "xUserId": "...", "handle": "alice", "displayName": "..." },
      "matchConfidence": "high",
      "sourceType": "new_follower",
      "discoveredAt": "2026-06-02T09:01:00Z"
    }
  ]
}
```

## Auth

Bearer API key.