> ## Documentation Index > Fetch the complete documentation index at: https://docs.manypi.com/llms.txt > Use this file to discover all available pages before exploring further. # Start a lead search > Launch the lead-generation agent against structured criteria, a saved search, or a set of seed leads ("find more like these"). The run is asynchronous: poll `GET /api/agents/runs` with the returned `conversation_id`. The run may pause with a clarifying question — answer it with `POST /api/agents/runs/{id}/reply` and the same run continues. `count` is clamped to the workspace's remaining lead capacity; when that happens the response carries a `clamped` block. A full workspace returns `403` with `code: "lead_limit"`. **With a saved search.** `criteria` sent alongside `profile_id` replaces the saved criteria as a whole — fields you leave out fall back to their defaults, not to the saved values. To change one field, read the saved search from `GET /api/leads/research-profiles`, merge your change, and send the full criteria. Because `save` defaults to `true`, the criteria you send are also written back to that saved search; send `save: false` to run without changing it. **Two responses that start no lead search.** Both apply only to a typed request, with no `profile_id` and no `seed_lead_ids`: - When `criteria` carries only a free-text `description` that does not read as a request for leads, ManyPI starts a plain agent run instead and the response includes `redirected: true`. Send `check_intent: false` to skip that check. - When the description names leads the workspace already has, the response is `{ "known": {...}, "description": "..." }` with no `run_id`, and no run starts. Send `force_search: true` to search anyway. Requires the `agents` permission. ## OpenAPI ````yaml POST /api/leads/research openapi: 3.1.0 info: title: ManyPI API description: >- The REST API behind ManyPI — AI lead generation, email validation, cold-email outreach, agent runs and web scraping. Every endpoint is authenticated with a ManyPI API key (`mpi_...`) or an OAuth 2.1 access token, and honours the permissions granted to that credential. version: 2.0.0 contact: name: ManyPI Support email: support@manypi.com url: https://manypi.com servers: - url: https://app.manypi.com description: Production security: - bearerAuth: [] tags: - name: Leads description: Find, store, enrich and manage leads. - name: Email validation description: Verify that lead addresses can receive mail. - name: Outreach description: Inboxes, sequences, campaigns, sending and replies. - name: Agent description: Agent runs, replies and skills. - name: Scraping description: Scrapers, runs and extracted data. - name: Endpoints description: Publish scrapers as typed REST endpoints. - name: Account description: Key validation and account information. paths: /api/leads/research: post: tags: - Leads summary: Start a lead search description: >- Launch the lead-generation agent against structured criteria, a saved search, or a set of seed leads ("find more like these"). The run is asynchronous: poll `GET /api/agents/runs` with the returned `conversation_id`. The run may pause with a clarifying question — answer it with `POST /api/agents/runs/{id}/reply` and the same run continues. `count` is clamped to the workspace's remaining lead capacity; when that happens the response carries a `clamped` block. A full workspace returns `403` with `code: "lead_limit"`. **With a saved search.** `criteria` sent alongside `profile_id` replaces the saved criteria as a whole — fields you leave out fall back to their defaults, not to the saved values. To change one field, read the saved search from `GET /api/leads/research-profiles`, merge your change, and send the full criteria. Because `save` defaults to `true`, the criteria you send are also written back to that saved search; send `save: false` to run without changing it. **Two responses that start no lead search.** Both apply only to a typed request, with no `profile_id` and no `seed_lead_ids`: - When `criteria` carries only a free-text `description` that does not read as a request for leads, ManyPI starts a plain agent run instead and the response includes `redirected: true`. Send `check_intent: false` to skip that check. - When the description names leads the workspace already has, the response is `{ "known": {...}, "description": "..." }` with no `run_id`, and no run starts. Send `force_search: true` to search anyway. Requires the `agents` permission. operationId: startLeadResearch requestBody: required: true content: application/json: schema: type: object properties: criteria: $ref: '#/components/schemas/LeadResearchCriteria' profile_id: type: string format: uuid description: >- Re-run a saved search. Its criteria are used when `criteria` is omitted; when `criteria` is sent, it replaces them entirely. seed_lead_ids: type: array maxItems: 50 items: type: string format: uuid description: Seed the search from existing leads ("find similar"). save: type: boolean default: true description: >- Persist the criteria as a reusable saved search. With `profile_id`, writes them back to that saved search. name: type: string maxLength: 120 kind: type: string enum: - icp - similar check_intent: type: boolean default: true description: >- Check that a free-text-only request reads as a lead search, and start a plain agent run when it does not. Send `false` when your integration only ever sends lead searches. force_search: type: boolean default: false description: >- Search even when the description names leads the workspace already has. example: criteria: description: E-commerce agencies building Shopify stores for DTC brands locations: - Germany - Austria industries: - Marketing agency - E-commerce company_size: 5-50 employees titles: - Founder - Head of Growth exclusions: - SEO-only agencies required_fields: - email extra_columns: - name: Ecommerce platform description: Shopify, WooCommerce, custom or unknown count: 25 responses: '200': description: >- A run was created — or, when `known` is present instead of `run_id`, the workspace already holds the leads the description names and no run was started. content: application/json: schema: type: object properties: run_id: type: string format: uuid description: Absent when the response carries `known`. conversation_id: type: string format: uuid status: type: string count: type: integer description: Leads the run will actually try to save, after clamping. profile: type: object nullable: true clamped: type: object description: Present only when `count` was reduced to fit the plan. properties: requested: type: integer allowed: type: integer limit: type: integer redirected: type: boolean description: >- Present and `true` when the request did not read as a lead search and a plain agent run was started instead. See `check_intent`. known: type: object description: >- Present instead of `run_id` when the description names leads the workspace already has. Holds those leads; no run was started. See `force_search`. description: type: string description: >- The description that was matched, returned alongside `known`. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- The workspace is storing all the leads the plan allows (`code: "lead_limit"`). content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: LeadResearchCriteria: type: object description: >- The structured search. The description does most of the work; the rest is what the agent enforces. properties: description: type: string maxLength: 4000 description: Free-text ideal-customer description. count: type: integer minimum: 1 default: 25 description: How many NEW leads to save. Clamped to remaining plan capacity. locations: type: array maxItems: 20 items: type: string industries: type: array maxItems: 20 items: type: string company_size: type: string maxLength: 160 description: 'Free text on purpose: "5-50 employees", "Series A", "under $5M ARR".' titles: type: array maxItems: 20 items: type: string description: Roles to reach inside each company. keywords: type: array maxItems: 30 items: type: string description: Signals a company must show. exclusions: type: array maxItems: 30 items: type: string description: Hard excludes — matches are dropped, not saved. required_fields: type: array maxItems: 6 items: type: string enum: - email - phone - full_name - title - linkedin_url - location default: - email description: A lead missing one of these is not saved. extra_columns: type: array maxItems: 10 items: type: object properties: name: type: string maxLength: 60 description: type: string maxLength: 300 description: Extra researched columns, written to the lead's custom fields. sources: type: array maxItems: 10 items: type: string description: 'Where to look: directories, marketplaces, maps, specific sites.' notes: type: string maxLength: 2000 Error: type: object properties: error: description: >- Human-readable message. A few validation failures (creating or updating an endpoint, bulk lead updates and deletes) send a list of the individual problems here instead of one string. oneOf: - type: string - type: array items: type: object properties: path: type: array items: type: - string - integer message: type: string code: type: string description: >- A machine-readable code on gated failures: `lead_limit`, `outreach_locked`, `validation_credits_exhausted`. details: description: >- Extra detail on some failures, such as the list of parameters that failed an endpoint's `param_schema`. responses: BadRequest: description: The request body or parameters failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: >- Missing, invalid or expired credential — or a key that lacks the permission this route requires. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: >- A ManyPI API key (`mpi_...`) from the profile menu → API Access in the dashboard, or an OAuth 2.1 access token obtained through the MCP consent flow. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.