> ## 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 lead searches > Cursor-paginate the workspace’s lead searches (newest-first, stable under concurrent changes) for history and to discover ids to poll. In-progress chat drafts are not listed. Requires one of the following scopes: `leadfinder:read`, `all:read`, `all:all`. ## OpenAPI ````yaml /openapi.json get /v1/lead-searches 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/lead-searches: get: tags: - Lead Finder summary: List lead searches description: >- Cursor-paginate the workspace’s lead searches (newest-first, stable under concurrent changes) for history and to discover ids to poll. In-progress chat drafts are not listed. Requires one of the following scopes: `leadfinder:read`, `all:read`, `all:all`. operationId: leadSearches_list parameters: - 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: 100 default: 50 example: 50 type: number responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/LeadSearchListApiResponseDto' '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 '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: LeadSearchListApiResponseDto: type: object properties: data: type: array items: $ref: '#/components/schemas/LeadSearchListItemApiDto' meta: $ref: '#/components/schemas/LeadSearchListMetaApiDto' required: - data - meta ApiErrorDto: type: object properties: error: $ref: '#/components/schemas/ApiErrorBodyDto' required: - error LeadSearchListItemApiDto: type: object properties: id: type: string format: uuid example: a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60 query: type: string example: dental clinics in Berlin description: The natural-language query this search was started from. status: type: string enum: - draft - queued - discovering - processing - crawling - enriching - verifying - completed - stopped - failed example: completed description: >- Lifecycle status. Terminal states are `completed`, `stopped`, `failed`; everything else is still running. searchMode: type: string enum: - companies - people example: companies description: Whether the search discovers companies or people. maxResults: type: number example: 500 description: The requested discovery cap for this search. createdAt: type: string format: date-time description: When the search was created. completedAt: type: string format: date-time nullable: true description: When the search reached a terminal state; null while still running. required: - id - query - status - searchMode - maxResults - createdAt LeadSearchListMetaApiDto: type: object properties: hasMore: type: boolean example: true description: Whether more searches 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 securitySchemes: ApiKey: scheme: bearer bearerFormat: mb_live_… type: http ```` ## Related topics - [List campaign leads](/api-reference/leads/list-campaign-leads.md) - [Get a lead search](/api-reference/lead-finder/get-a-lead-search.md) - [Search leads by email](/api-reference/leads/search-leads-by-email.md) - [Leads](/leads.md) - [Lead Finder](/lead-finder.md)