> ## 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. # Get one Lead Finder search and paginated results > Get one Lead Finder search and paginated results **CLI:** ```bash theme={null} puffle lead-finder --id puffle lead-finder --id --limit --offset --cursor ``` ## Overview Get one Lead Finder search and paginated results This page documents `get /api/lead-finder/{id}`. 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 get /api/lead-finder/{id} 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}: get: tags: - Lead Finder summary: Get one Lead Finder search and paginated results description: Get one Lead Finder search and paginated results operationId: leadFinder.get parameters: - name: id in: path required: true schema: type: string format: uuid - name: limit in: query required: false schema: type: integer exclusiveMinimum: true maximum: 500 minimum: 0 - name: offset in: query required: false schema: type: integer minimum: 0 maximum: 9007199254740991 - name: cursor in: query required: false schema: type: integer minimum: 0 maximum: 9007199254740991 responses: '200': description: Lead Finder detail. 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 results: type: array items: type: object properties: resultId: type: string format: uuid searchId: type: string format: uuid runId: type: string format: uuid sourceId: type: string searchUrl: type: string query: type: string searchReason: type: string signalReason: type: string nullable: true title: type: string content: type: string occurredAt: type: string nullable: true author: nullable: true metadata: type: object additionalProperties: {} lead: nullable: true leadId: type: string format: uuid nullable: true canonicalLead: type: object properties: id: type: string format: uuid type: type: string enum: - person - company name: type: string title: type: string nullable: true company: type: string nullable: true companyDomain: type: string nullable: true email: type: string nullable: true linkedinUrl: type: string nullable: true required: - id - type - name - title - company - companyDomain - email - linkedinUrl additionalProperties: false nullable: true entityCompany: type: string nullable: true entityPerson: type: string nullable: true score: type: integer minimum: -9007199254740991 maximum: 9007199254740991 qualityTier: type: string enum: - excellent - good - possible - rejected nullable: true status: type: string createdAt: type: string required: - resultId - searchId - runId - sourceId - searchUrl - query - searchReason - signalReason - title - content - occurredAt - author - metadata - lead - leadId - canonicalLead - entityCompany - entityPerson - score - qualityTier - status - createdAt additionalProperties: false pagination: type: object properties: total: type: integer minimum: 0 maximum: 9007199254740991 limit: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 offset: type: integer minimum: 0 maximum: 9007199254740991 hasMore: type: boolean nextCursor: type: integer minimum: 0 maximum: 9007199254740991 nullable: true required: - total - limit - offset - hasMore - nextCursor additionalProperties: false latestRun: type: object properties: runId: type: string format: uuid status: type: string enum: - queued - running - completed - partial - failed - cancelled counts: type: object additionalProperties: type: number errors: type: array items: type: object properties: sourceId: type: string error: type: string code: type: string required: - sourceId - error additionalProperties: false sourceStatus: type: array items: type: object properties: sourceId: type: string status: type: string error: type: string queryDiagnostics: type: array items: type: object properties: query: type: string fetched: type: integer minimum: 0 maximum: 9007199254740991 normalized: type: integer minimum: 0 maximum: 9007199254740991 ranked: type: integer minimum: 0 maximum: 9007199254740991 leadExtracted: type: integer minimum: 0 maximum: 9007199254740991 apolloEnriched: type: integer minimum: 0 maximum: 9007199254740991 qualityKept: type: integer minimum: 0 maximum: 9007199254740991 stored: type: integer minimum: 0 maximum: 9007199254740991 maxResults: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 keywordDepthBoosted: type: boolean currentRunDepthExpanded: type: boolean searchAttempts: type: array items: type: object properties: attempt: type: integer exclusiveMinimum: true maximum: 9007199254740991 minimum: 0 stage: type: string enum: - exact - broadened providerQuery: type: string filters: type: object additionalProperties: anyOf: - type: string - type: number - type: boolean - type: array items: type: string reason: type: string fetched: type: integer minimum: 0 maximum: 9007199254740991 required: - attempt - stage - reason - fetched additionalProperties: false error: type: string required: - query - fetched - normalized - ranked - leadExtracted - qualityKept - stored - maxResults additionalProperties: false required: - sourceId - status additionalProperties: false triggerRunId: type: string nullable: true cancelledAt: type: string nullable: true createdAt: type: string updatedAt: type: string required: - runId - status - counts - errors - sourceStatus - triggerRunId - cancelledAt - createdAt - updatedAt additionalProperties: false nullable: true required: - search - results - pagination - latestRun 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 '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 '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_... ````