> ## Documentation Index > Fetch the complete documentation index at: https://docs.coldsend.pro/llms.txt > Use this file to discover all available pages before exploring further. # List campaign leads > **List all leads in a campaign** Retrieve a paginated list of leads with their status and details. ## Filtering Options - **status**: Filter by lead status (PENDING, SENT, OPENED, REPLIED, BOUNCED, UNSUBSCRIBED) - **search**: Search by email or name - **batch_id**: Filter by lead batch (upload source) ## Pagination - **page**: Page number (1-based) - **limit**: Items per page (1-100, default 20) ## Example Usage ```python import requests campaign_id = "550e8400-e29b-41d4-a716-446655440000" response = requests.get( f"https://api.coldsend.io/api/public/v1/campaigns/{campaign_id}/leads?status=PENDING", headers={"X-API-Key": "your-api-key"} ) print(response.json()) ``` ## OpenAPI ````yaml /public_openapi.json get /api/public/v1/campaigns/{campaign_id}/leads openapi: 3.0.3 info: title: ColdSend Public API description: >- Programmatic access to ColdSend for managing cold email campaigns and sender accounts. version: 1.0.0 contact: name: ColdSend Support email: support@coldsend.pro url: https://coldsend.pro servers: - url: https://api.coldsend.pro description: Production security: - ApiKeyAuth: [] paths: /api/public/v1/campaigns/{campaign_id}/leads: get: tags: - Leads summary: List campaign leads description: >- **List all leads in a campaign** Retrieve a paginated list of leads with their status and details. ## Filtering Options - **status**: Filter by lead status (PENDING, SENT, OPENED, REPLIED, BOUNCED, UNSUBSCRIBED) - **search**: Search by email or name - **batch_id**: Filter by lead batch (upload source) ## Pagination - **page**: Page number (1-based) - **limit**: Items per page (1-100, default 20) ## Example Usage ```python import requests campaign_id = "550e8400-e29b-41d4-a716-446655440000" response = requests.get( f"https://api.coldsend.io/api/public/v1/campaigns/{campaign_id}/leads?status=PENDING", headers={"X-API-Key": "your-api-key"} ) print(response.json()) ``` operationId: list_leads_api_public_v1_campaigns__campaign_id__leads_get parameters: - name: campaign_id in: path required: true schema: type: string format: uuid title: Campaign Id - name: page in: query required: false schema: type: integer minimum: 1 description: Page number default: 1 title: Page description: Page number - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Items per page default: 20 title: Limit description: Items per page - name: status_filter in: query required: false schema: type: string nullable: true title: Status Filter description: Filter by status description: Filter by status - name: search in: query required: false schema: type: string nullable: true title: Search description: Search by email or name description: Search by email or name - name: batch_id in: query required: false schema: type: string format: uuid nullable: true title: Batch Id description: Filter by batch ID description: Filter by batch ID responses: '200': description: Leads retrieved successfully content: application/json: schema: $ref: '#/components/schemas/LeadListResponse' '401': description: Missing or invalid API key '403': description: Insufficient permissions - requires 'leads:read' scope '404': description: Campaign not found '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: LeadListResponse: properties: success: type: boolean title: Success message: type: string title: Message leads: items: $ref: '#/components/schemas/LeadResponse' type: array title: Leads description: List of leads pagination: $ref: '#/components/schemas/PaginationMeta' description: Pagination information type: object required: - success - message - leads - pagination title: LeadListResponse description: Response for listing campaign leads. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError LeadResponse: properties: lead_id: type: string format: uuid title: Lead Id description: Lead ID batch_id: type: string format: uuid nullable: true title: Batch Id description: Batch ID this lead belongs to email: type: string title: Email description: Lead email address first_name: type: string nullable: true title: First Name description: First name last_name: type: string nullable: true title: Last Name description: Last name company: type: string nullable: true title: Company description: Company name custom_fields: additionalProperties: true type: object title: Custom Fields description: Custom lead fields status: type: string title: Status description: Lead status sequence_step: type: integer title: Sequence Step description: Current sequence step default: 0 next_followup_scheduled_for: type: string format: date-time nullable: true title: Next Followup Scheduled For description: When the next pending follow-up is scheduled last_contacted_at: type: string format: date-time nullable: true title: Last Contacted At description: Last contact timestamp opened_at: type: string format: date-time nullable: true title: Opened At description: Email opened timestamp replied_at: type: string format: date-time nullable: true title: Replied At description: Reply timestamp email_opened: type: boolean title: Email Opened description: Whether email was opened default: false email_replied: type: boolean title: Email Replied description: Whether lead replied default: false unsubscribed: type: boolean title: Unsubscribed description: Whether lead unsubscribed default: false created_at: type: string format: date-time title: Created At description: Lead creation timestamp delivery_status: type: string nullable: true title: Delivery Status description: Delivery status from Azure (latest email) current_intent_tag: $ref: '#/components/schemas/LeadIntentTagInfo' nullable: true description: Latest INTENT-group thread tag across the lead's threads (rollup) type: object required: - lead_id - batch_id - email - first_name - last_name - company - status - last_contacted_at - opened_at - replied_at - created_at title: LeadResponse description: Response schema for individual lead. PaginationMeta: properties: page: type: integer title: Page limit: type: integer title: Limit total: type: integer title: Total pages: type: integer title: Pages has_next: type: boolean title: Has Next has_prev: type: boolean title: Has Prev type: object required: - page - limit - total - pages - has_next - has_prev title: PaginationMeta description: Pagination metadata schema. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError LeadIntentTagInfo: properties: tag_id: type: string format: uuid title: Tag Id description: Tag ID tag_name: type: string title: Tag Name description: Tag display name tag_color: type: string nullable: true title: Tag Color description: Tag hex color is_ai_applied: type: boolean title: Is Ai Applied description: Whether AI or manual default: true confidence: type: number nullable: true title: Confidence description: AI confidence 0-1 type: object required: - tag_id - tag_name title: LeadIntentTagInfo description: Lightweight intent tag summary for lead list responses. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key with format cs_live_xxx ````