> ## Documentation Index > Fetch the complete documentation index at: https://docs.puffle.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run one Lead Finder search > Run one Lead Finder search **CLI:** ```bash theme={null} puffle lead-finder run create --id puffle lead-finder run create --id --continuation ``` ## Overview Run one Lead Finder search This page documents `post /api/lead-finder/{id}/run`. Use the request and response sections on this page for accepted parameters, payload fields, response fields, and authentication behavior. ## AI agent notes * Confirm the operation matches the user's intent before calling it. * For write operations, confirm the user intends to change state. * Surface validation, permission, and not-found errors instead of retrying unchanged. ## OpenAPI ````yaml post /api/lead-finder/{id}/run openapi: 3.0.3 info: title: Puffle API version: 1.0.0 description: >- HTTP API for the Puffle GTM platform - Feed and Lead Finder search preparation, campaign-backed Outbound execution, Puffle Agent runs, sender management, and Unibox reply workflows. Designed for operation by both humans and autonomous AI agents. Agents should start at the [Agent Playbook](/guides/agent-playbook) which prescribes a workspace-context check (`GET /api/context`) and core user journeys with exact call ordering. contact: name: Puffle Support url: https://puffle.ai servers: - url: https://app.puffle.ai description: Production security: - bearerAuth: [] tags: - name: Campaigns description: >- Campaign-backed Outbound execution. These endpoints manage draft, launching, active, paused, and completed Outbound runs with sequence nodes, contacts, and sender accounts. - name: Accounts description: Signed-in user account, settings, and workspace context endpoints. - name: Billing description: Billing customer portal and account billing endpoints. - name: Senders description: >- Connected sender accounts, email inboxes, sending domains, DNS verification, warmup, and sender capacity. - name: Socials description: >- Read connected LinkedIn and X accounts, review current and archived posts, and reconcile publication status. Creating, editing, scheduling, publishing, OAuth connection, analytics, and mentions remain dashboard-managed workflows and are not part of the public Bearer-token API. paths: /api/lead-finder/{id}/run: post: tags: - Lead Finder summary: Run one Lead Finder search description: Run one Lead Finder search operationId: leadFinder.runOne parameters: - name: id in: path required: true schema: type: string format: uuid - name: continuation in: query required: false schema: type: string enum: - 'true' - 'false' responses: '200': description: Lead Finder Run outcome. content: application/json: schema: type: object properties: search: type: object properties: searchId: type: string format: uuid title: type: string description: type: string kind: type: string enum: - recurring - static surface: type: string enum: - lead-finder - feed scheduleEnabled: type: boolean definitionHash: type: string minLength: 64 maxLength: 64 nullable: true intent: type: string sellerContext: type: string sourcePlans: type: array items: type: object properties: sourceId: type: string enum: - linkedin_posts - linkedin_people - news - reddit - hacker_news - x_twitter - hiring_cafe - github query: minItems: 1 type: array items: type: string minLength: 1 maxLength: 240 reason: type: string minLength: 1 maxLength: 240 resultTarget: oneOf: - type: object properties: mode: type: string enum: - count count: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 required: - mode - count additionalProperties: false - type: object properties: mode: type: string enum: - all required: - mode additionalProperties: false recurrence: type: string enum: - finite - monitoring geography: type: object properties: mode: type: string enum: - explicit countryCodes: minItems: 1 type: array items: type: string description: >- String value with endpoint-specific validation. cityNames: type: array items: type: string minLength: 1 required: - mode - countryCodes additionalProperties: false companySize: type: object properties: min: type: integer minimum: 0 maximum: 9007199254740991 max: type: integer minimum: 0 maximum: 9007199254740991 additionalProperties: false personCriteria: minItems: 1 maxItems: 12 type: array items: type: object properties: id: type: string maxLength: 60 description: >- String value with endpoint-specific validation. kind: type: string enum: - current_title values: minItems: 1 maxItems: 12 type: array items: type: string minLength: 1 maxLength: 120 required: - id - kind - values additionalProperties: false unresolvedPreferences: maxItems: 3 type: array items: type: string minLength: 1 maxLength: 240 companyCriteria: description: >- Every separate entry is AND-combined and must pass. Put OR alternatives in one criterion value instead of separate entries. maxItems: 12 type: array items: type: object properties: id: type: string maxLength: 60 description: >- String value with endpoint-specific validation. kind: type: string enum: - business_model - customer_type - offering - industry - exclusion - other operator: type: string enum: - is - is_not value: type: string minLength: 1 maxLength: 120 required: - id - kind - operator - value additionalProperties: false rankedCompanyCohort: oneOf: - type: object properties: kind: type: string enum: - default limit: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 required: - kind additionalProperties: false - type: object properties: kind: type: string enum: - named - attached sourceId: type: string minLength: 1 maxLength: 120 limit: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 required: - kind - sourceId additionalProperties: false - type: object properties: kind: type: string enum: - metric metric: type: string enum: - revenue - market_cap limit: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 required: - kind - metric additionalProperties: false required: - sourceId - query - reason additionalProperties: false details: type: object properties: channel: type: string signal: type: string expectedLead: type: string whyThisShouldWork: type: string plannerAssumedPreferences: type: array items: type: string additionalProperties: false lastRunId: type: string format: uuid nullable: true outboundCampaignId: type: string format: uuid nullable: true leadCount: type: integer minimum: 0 maximum: 9007199254740991 resultCount: type: integer minimum: 0 maximum: 9007199254740991 contactedCount: type: integer minimum: 0 maximum: 9007199254740991 nextRunAt: type: string nullable: true createdAt: type: string updatedAt: type: string required: - searchId - title - description - kind - surface - scheduleEnabled - definitionHash - intent - sellerContext - sourcePlans - details - lastRunId - outboundCampaignId - leadCount - resultCount - contactedCount - nextRunAt - createdAt - updatedAt additionalProperties: false run: type: object properties: runId: type: string minLength: 1 triggerRunId: type: string minLength: 1 nullable: true status: type: string enum: - queued - running - completed - partial - failed - cancelled continuationRetryAfter: type: string format: date-time nullable: true counts: type: object additionalProperties: type: number required: - runId - triggerRunId - status - continuationRetryAfter - counts additionalProperties: false disposition: type: string enum: - queued - existing dispatch: type: string enum: - recorded - accepted_unrecorded - existing required: - search - run - disposition - dispatch additionalProperties: false '401': description: Unauthorized. content: application/json: schema: type: object properties: error: type: string message: type: string sourceId: type: string code: type: string alternatives: type: array items: type: string retryable: type: boolean alert: type: boolean action: type: object properties: type: type: string enum: - navigate label: type: string href: type: string required: - type - label - href additionalProperties: false required: - error additionalProperties: false '402': description: Action required. content: application/json: schema: type: object properties: error: type: string message: type: string sourceId: type: string code: type: string alternatives: type: array items: type: string retryable: type: boolean alert: type: boolean action: type: object properties: type: type: string enum: - navigate label: type: string href: type: string required: - type - label - href additionalProperties: false required: - error additionalProperties: false '404': description: Not found. content: application/json: schema: type: object properties: error: type: string message: type: string sourceId: type: string code: type: string alternatives: type: array items: type: string retryable: type: boolean alert: type: boolean action: type: object properties: type: type: string enum: - navigate label: type: string href: type: string required: - type - label - href additionalProperties: false required: - error additionalProperties: false '409': description: Search cannot run. content: application/json: schema: type: object properties: error: type: string message: type: string sourceId: type: string code: type: string alternatives: type: array items: type: string retryable: type: boolean alert: type: boolean action: type: object properties: type: type: string enum: - navigate label: type: string href: type: string required: - type - label - href additionalProperties: false required: - error additionalProperties: false '500': description: Server error. content: application/json: schema: type: object properties: error: type: string message: type: string sourceId: type: string code: type: string alternatives: type: array items: type: string retryable: type: boolean alert: type: boolean action: type: object properties: type: type: string enum: - navigate label: type: string href: type: string required: - type - label - href additionalProperties: false required: - error additionalProperties: false components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: pk_live_... ````