---
title: "List Leads"
method: GET
path: "/api/v1/campaigns/{campaign_id}/leads"
tags: ["Campaigns"]
---

# List Leads

`GET /api/v1/campaigns/{campaign_id}/leads`

## Request

- Base URL: `http://localhost:3009`
- URL: `http://localhost:3009/api/v1/campaigns/{campaign_id}/leads`
- Auth: HTTP bearer

Returns a campaign's leads, newest first. Filter by `status` (e.g. `replied`, `in_sequence`) or `search` an email substring.

Note that `added` means "not yet enrolled", which in practice only happens while the campaign has no published sequence — leads added to a paused campaign are already `in_sequence` with their next step held.

## Path parameters

- `campaign_id` string, required

## Query parameters

- `page_no` string
- `page_size` string
- `status` 'added' | 'in_sequence' | 'completed' | 'removed' | 'replied' | 'responded' | 'unsubscribed' | 'suppressed' | 'bounced'
- `search` string

## Response `200`

Default Response

- object
  - `status` integer
  - `data` object
    - `leads` CampaignLead[]
      - `id` string: Lead ID, derived deterministically from the email address
      - `email` string: Lead email address
      - `name` string: Lead name
      - `status` 'added' | 'in_sequence' | 'completed' | 'removed' | 'replied' | 'responded' | 'unsubscribed' | 'suppressed' | 'bounced': `added` (awaiting enrolment), `in_sequence` (running), then a terminal state: `completed`, `replied`, `responded`, `bounced`, `unsubscribed`, `suppressed`, `removed`.
      - `email_provider` string, nullable: Mail provider derived from the address's MX records, e.g. `google`, `microsoft`, `unknown`
      - `fields` object: Custom field values, keyed by field name from the campaign's `lead_schema`
      - `current_node_id` string, nullable: Sequence node the lead is currently at
      - `next_run_at` string, date-time, nullable: When the lead's next step is due
      - `replied_at` string, date-time, nullable
      - `created_at` string, date-time
    - `total_count` integer
    - `page_no` integer
    - `page_size` integer

## Other responses

- `401`: Unauthorized — missing or invalid API key
- `403`: Forbidden. `code` says which permission refused: ROLE_FORBIDDEN (your role), INSUFFICIENT_SCOPE (the API key's scopes), WORKFLOW_FORBIDDEN (no access to the workflow), KEY_WORKFLOW_FORBIDDEN (the API key's workflow restriction).
- `404`: Campaign not found
- `429`: Too Many Requests — rate limit exceeded. Check `Retry-After` header for seconds until the limit resets.

---

[API](https://skmtc.dev/floqer/apis/floqer-public-api.md) - [All operations](https://skmtc.dev/floqer/apis/floqer-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/floqer/apis/floqer-public-api/revisions/fce50dc07b20?raw)