> ## Documentation Index > Fetch the complete documentation index at: https://developer.mailbeast.ai/llms.txt > Use this file to discover all available pages before exploring further. # List campaign leads > Page through a campaign’s leads with filters (status, tags, search). Requires one of the following scopes: `leads:read`, `leads:all`, `all:read`, `all:all`. ## OpenAPI ````yaml /openapi.json get /v1/campaigns/{cid}/leads openapi: 3.0.0 info: title: MailBeast Public API description: >- Task-shaped REST API for campaigns, leads, deliverability, verification and lead discovery. Authenticate with an API key (`Authorization: Bearer mb_live_…`); the workspace is resolved from the key. version: '1' contact: {} servers: - url: https://api.mailbeast.ai security: [] tags: - name: API Keys description: Create, list and revoke API keys programmatically. - name: Campaigns description: Create, configure, launch and monitor email campaigns. - name: Leads description: Add, read, update and bulk-manage a campaign’s leads. - name: Workspace description: Read usage, subscription and workspace identity. - name: Email Accounts description: >- Connect and manage the sending mailboxes your campaigns send from (SMTP/IMAP or native OAuth). - name: Analytics description: Engagement reporting – per campaign, over time, and across the workspace. - name: Lead Finder description: >- Discover new companies and leads. List past searches and poll a running search’s progress. paths: /v1/campaigns/{cid}/leads: get: tags: - Leads summary: List campaign leads description: >- Page through a campaign’s leads with filters (status, tags, search). Requires one of the following scopes: `leads:read`, `leads:all`, `all:read`, `all:all`. operationId: campaignLeads_list parameters: - name: cid required: true in: path schema: type: string format: uuid example: a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60 - name: cursor required: false in: query description: >- Opaque cursor from a previous response’s `meta.nextCursor`. Omit for the first page. Results are ordered newest-first and stable under concurrent changes. schema: example: >- eyJ0cyI6IjIwMjYtMDctMDJUMDA6MDA6MDAuMDAwWiIsImlkIjoiM2YxYzJiN2UtOWE0ZC00ZTE4LWIyYzEtNmQ4ZjVhMGU3YzkzIn0 type: string - name: limit required: false in: query schema: minimum: 1 maximum: 250 default: 50 example: 50 type: number - name: search required: false in: query description: Match on email / first name / last name / company. schema: example: acme type: string - name: status required: false in: query description: Filter by lead status. schema: type: string enum: - not_contacted - scheduled - email_sent - failed - skipped - lead_replied_interested - lead_replied_meeting_request - lead_replied_out_of_office - lead_replied_bounce - lead_replied_wrong_person - lead_replied_not_interested - lead_replied_unsubscribed - lead_replied_uncategorized - lead_converted - lead_lost - blacklisted - name: tags required: false in: query description: >- Has ANY of these tags. Repeat the param (`?tags=a&tags=b`) or pass a single value. schema: example: - vip - q4 type: array items: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/LeadListApiResponseDto' '400': description: The request body or parameters failed validation. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: invalid_request_error code: validation_failed message: One or more fields are invalid. status: 400 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f details: - name should not be empty '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: authentication_error code: unauthenticated message: Missing or invalid API key. status: 401 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f '403': description: >- The key lacks a required scope, or the plan does not include API access. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: authorization_error code: permission_denied message: This API key is missing the required scope. status: 403 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f '404': description: The resource does not exist in your workspace. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: invalid_request_error code: not_found message: Resource not found. status: 404 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f '429': description: >- Rate limit exceeded - retry after the interval in the Retry-After header. content: application/json: schema: $ref: '#/components/schemas/ApiErrorDto' example: error: type: rate_limit_error code: rate_limited message: >- Too many requests. Retry after the interval in the Retry-After header. status: 429 requestId: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f retryAfter: 30 security: - ApiKey: [] components: schemas: LeadListApiResponseDto: type: object properties: data: type: array items: $ref: '#/components/schemas/LeadApiDto' meta: $ref: '#/components/schemas/LeadListMetaDto' required: - data - meta ApiErrorDto: type: object properties: error: $ref: '#/components/schemas/ApiErrorBodyDto' required: - error LeadApiDto: type: object properties: id: type: string format: uuid example: c9e5b1a3-7f24-4d80-a6b9-2e4f8c0d1a37 email: type: string example: jane@acme.com firstName: type: string nullable: true example: Jane lastName: type: string nullable: true example: Doe companyName: type: string nullable: true example: Acme Inc jobTitle: type: string nullable: true example: VP Sales website: type: string nullable: true example: https://acme.com linkedinProfile: type: string nullable: true example: https://www.linkedin.com/in/janedoe location: type: string nullable: true example: New York, US tags: example: - vip - q4 type: array items: type: string customFields: type: object additionalProperties: true example: industry: SaaS status: type: string enum: - not_contacted - scheduled - email_sent - failed - skipped - lead_replied_interested - lead_replied_meeting_request - lead_replied_out_of_office - lead_replied_bounce - lead_replied_wrong_person - lead_replied_not_interested - lead_replied_unsubscribed - lead_replied_uncategorized - lead_converted - lead_lost - blacklisted example: not_contacted verification: $ref: '#/components/schemas/LeadVerificationView' provider: type: string nullable: true example: google metrics: $ref: '#/components/schemas/LeadMetricsView' sequenceProgress: description: Live sequence progress - included on the single-lead detail view. allOf: - $ref: '#/components/schemas/LeadSequenceProgressView' createdAt: type: string format: date-time lastContactedAt: type: string format: date-time nullable: true lastRepliedAt: type: string format: date-time nullable: true required: - id - email - tags - customFields - status - verification - metrics - createdAt LeadListMetaDto: type: object properties: hasMore: type: boolean example: true description: Whether more leads are available after this page. nextCursor: type: string nullable: true description: >- Pass as `?cursor=` to fetch the next page; null when `hasMore` is false. example: >- eyJ0cyI6IjIwMjYtMDctMDJUMDA6MDA6MDAuMDAwWiIsImlkIjoiM2YxYzJiN2UtOWE0ZC00ZTE4LWIyYzEtNmQ4ZjVhMGU3YzkzIn0 required: - hasMore ApiErrorBodyDto: type: object properties: type: type: string example: authorization_error description: Broad error class. code: type: string example: permission_denied description: Stable machine-readable code to switch on. message: type: string example: This API key is missing the required scope. status: type: number example: 403 requestId: type: string example: e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f description: Correlation id - quote it in support requests. details: description: Field-level validation messages (present on validation errors). example: - name should not be empty type: array items: type: string retryAfter: type: number description: Seconds to wait before retrying (present on 429 responses). example: 30 required: - type - code - message - status - requestId LeadVerificationView: type: object properties: status: type: string nullable: true example: valid subStatus: type: string nullable: true example: email_ok LeadMetricsView: type: object properties: sent: type: number example: 2 opened: type: number example: 1 clicked: type: number example: 0 replied: type: number example: 0 required: - sent - opened - clicked - replied LeadSequenceProgressView: type: object properties: totalSteps: type: number example: 3 sentCount: type: number example: 1 plannedCount: type: number example: 1 failedCount: type: number example: 0 nextPlannedAt: type: string format: date-time nullable: true description: When the next step is scheduled to send; null if none pending. required: - totalSteps - sentCount - plannedCount - failedCount securitySchemes: ApiKey: scheme: bearer bearerFormat: mb_live_… type: http ```` ## Related topics - [List campaigns](/api-reference/campaigns/list-campaigns.md) - [List lead searches](/api-reference/lead-finder/list-lead-searches.md) - [List emails](/api-reference/emails/list-emails.md) - [Campaigns](/campaigns.md) - [Start campaign](/api-reference/campaigns/start-campaign.md)