> ## Documentation Index > Fetch the complete documentation index at: https://docs.loice.ai/llms.txt > Use this file to discover all available pages before exploring further. # Poll a lead-search run > Returns the status of a lead-search run plus one server page of its delivered results (25 per page — pass `?page=` for the rest). Poll it every few seconds while `status` is `queued`/`processing`/`cancelling`; a terminal `status` (`completed`/`cancelled`/`failed`) carries the final `deliveredCount` and `creditsCharged`. Results already delivered remain readable after the run finishes. #### Billing Free — this endpoint does not consume points. ## OpenAPI ````yaml /openapi.json get /api/v1/lead-search/runs/{runId} openapi: 3.1.0 info: title: Loice API version: v1 description: >- The Loice API finds and verifies professional contact data. Every capability is exposed here, key-authenticated and rate-limited; the web app is a client of the same platform. **Authentication** — pass your workspace API key on every request (except the API description) as `Authorization: Bearer loice_sk_…`. Keys are created under Settings → API Keys. **Billing** — operations are billed in points against your workspace balance. Each operation below states when the charge applies. The current cost of every operation is shown in the app under [Settings → Billing](https://app.loice.ai/settings/account?tab=billing) and in the live API description, `GET /api/v1/openapi.json`. Calls that fail because of a system or provider error (timeouts, upstream failures, our defects) are not billed, and rate-limited calls are rejected before any billable work. Check headroom with `GET /api/v1/points`. Where an operation documents an `Idempotency-Key` header, send one to retry safely: a repeated request returns the original outcome and is not charged again. **Errors** — every non-200 response has the shape `{ "error": { "message": "…" } }`. Operations whose error responses document an `error.code` also return that machine-readable code beside the message; branch on the code, not the text. servers: - url: https://app.loice.ai security: [] paths: /api/v1/lead-search/runs/{runId}: get: summary: Poll a lead-search run description: >- Returns the status of a lead-search run plus one server page of its delivered results (25 per page — pass `?page=` for the rest). Poll it every few seconds while `status` is `queued`/`processing`/`cancelling`; a terminal `status` (`completed`/`cancelled`/`failed`) carries the final `deliveredCount` and `creditsCharged`. Results already delivered remain readable after the run finishes. #### Billing Free — this endpoint does not consume points. parameters: - schema: type: string description: Run id from the `POST /api/v1/lead-search` response. required: true description: Run id from the `POST /api/v1/lead-search` response. name: runId in: path - schema: type: integer minimum: 1 description: 1-based results page (default 1); 25 items per page. required: false description: 1-based results page (default 1); 25 items per page. name: page in: query responses: '200': description: The run’s current status and one page of its results. content: application/json: schema: type: object properties: data: type: object properties: run: type: object properties: id: type: string description: >- Run id — poll it via `GET /api/v1/lead-search/runs/{runId}`. kind: type: string enum: - criteria - employees description: >- Always `criteria` on v1 (a criteria search). Employee Finder runs are not part of the public API and answer 404. lookupMode: type: - string - 'null' enum: - domain - linkedin description: >- Employee Finder runs only; null for a criteria run. lookupInput: type: - string - 'null' description: >- Employee Finder runs only; null for a criteria run. status: type: string enum: - queued - processing - cancelling - completed - cancelled - failed description: >- Lifecycle state. `queued`/`processing`/`cancelling` are active — keep polling; `completed`/`cancelled`/`failed` are terminal. requestedCount: type: integer description: Leads requested for this run. deliveredCount: type: integer description: >- Distinct leads delivered so far — the only number billed. sourceTotalElements: type: - integer - 'null' description: >- Total results the source reports for these criteria (set from the first fetched page); the browsable window is capped at 100 pages. sourceTotalPages: type: - integer - 'null' description: >- Source-reported page count (capped at 100 by the source). sourceExhausted: type: boolean description: >- True when the source ran out of matches before `requestedCount`. continuedFromId: type: - string - 'null' description: >- Id of the run this one continues, when it is a continuation. unitCost: type: integer description: Points per delivered lead. maxCost: type: integer description: >- Worst-case cost disclosed up front: `unitCost × requestedCount` (reserved at creation; the unused remainder frees at finalize). creditsCharged: type: - integer - 'null' description: >- Points actually debited — set at finalize to `deliveredCount × unitCost`, null while the run is active. An empty run charges 0. error: type: - string - 'null' description: >- Failure reason key when `status` is `failed` (e.g. `search-failed`). criteria: type: object additionalProperties: type: array items: type: string description: >- Echo of the normalized search criteria the run executes. createdAt: type: string description: ISO timestamp the run was created. startedAt: type: - string - 'null' description: ISO timestamp processing began, null while queued. finishedAt: type: - string - 'null' description: ISO timestamp the run reached a terminal state. required: - id - kind - lookupMode - lookupInput - status - requestedCount - deliveredCount - sourceTotalElements - sourceTotalPages - sourceExhausted - continuedFromId - unitCost - maxCost - creditsCharged - error - criteria - createdAt - startedAt - finishedAt results: type: object properties: page: type: integer description: The 1-based results page served. pageSize: type: integer description: Results per page (25). totalDelivered: type: integer description: Total delivered results across all pages. items: type: array items: anyOf: - type: object properties: id: type: string description: Stable id of this delivered result row. position: type: integer description: >- 0-based delivery position within the run. sourcePage: type: - integer - 'null' description: >- Which source page delivered this lead (as-if-local paging). name: type: - string - 'null' description: >- Deprecated — use person.fullName. Display name as the source shows it. title: type: - string - 'null' description: >- Deprecated — use person.title. Current title, when stated. company: type: - string - 'null' description: >- Deprecated — use companyProfile.name. Current employer as the source states it. location: type: - string - 'null' description: Deprecated — use person.location. industry: type: - string - 'null' description: >- Deprecated — use companyProfile.industry. Industry annotation, null until/unless annotated. linkedinUrl: type: string description: >- Public profile URL — feed it into `POST /api/v1/find` (linkedin mode) for a verified email. publicIdentifier: type: - string - 'null' description: >- Deprecated — use person.linkedinUrl. The profile slug, when stated. photoImageUrl: type: - string - 'null' description: >- Deprecated — use person.avatarUrl. Owned photo address, when mirrored. revealedEmail: type: - string - 'null' description: >- Email revealed for this lead, when one has been. revealedEmailStatus: type: - string - 'null' companyProfile: allOf: - $ref: '#/components/schemas/Company' - description: >- The canonical Company for this lead — the same schema `POST /api/v1/company` returns. Built from our company record when we hold a fresh one, otherwise from what the result observed (then `confirmedAt` is null and unobserved keys are null). person: allOf: - $ref: '#/components/schemas/Person' - type: object description: >- THE canonical Person for this lead. `person.company` is the same object as `companyProfile`. required: - id - position - sourcePage - name - title - company - location - industry - linkedinUrl - publicIdentifier - photoImageUrl - revealedEmail - revealedEmailStatus - companyProfile - person - $ref: '#/components/schemas/ErasedRunResult' required: - page - pageSize - totalDelivered - items required: - run - results required: - data example: data: run: id: cmf3x0v2b0001abcd status: processing requestedCount: 500 deliveredCount: 175 sourceExhausted: false sourceTotalElements: 23000 sourceTotalPages: 100 continuedFromId: null unitCost: 1 maxCost: 500 creditsCharged: null error: null criteria: jobTitle: - Head of Sales location: - Germany headcount: - 51-200 createdAt: '2026-09-01T09:00:00.000Z' startedAt: '2026-09-01T09:00:02.000Z' finishedAt: null results: page: 1 pageSize: 25 totalDelivered: 175 items: - id: cmf3x1a9k0007abcd position: 0 sourcePage: 1 name: Holger Frank title: Head Of Sales company: Sales People GmbH location: Mannheim, Baden-Württemberg, Germany industry: null linkedinUrl: >- https://www.linkedin.com/in/ACwAADQwgVsBH0t8Ns1HcaFODvoUSy9rtijQwPk publicIdentifier: null revealedEmail: null revealedEmailStatus: null companyProfile: name: Sales People GmbH linkedinUrl: null tagline: null description: null industry: null employeeBand: null employeeCount: null followerCount: null websiteUrl: null websiteDomain: null headquarters: null hqLocality: null hqRegion: null hqCountry: null foundedYear: null companyType: null specialties: [] logoUrl: null logoImageUrl: null phone: null email: null xUrl: null facebookUrl: null instagramUrl: null youtubeUrl: null confirmedAt: null '401': description: >- API key missing (`Missing API key. Pass it as: Authorization: Bearer `), invalid (`Invalid API key`), or expired (`This API key has expired`). content: application/json: schema: type: object properties: error: type: object properties: message: type: string required: - message required: - error '404': description: >- `not_found`: no such run for this workspace — an unknown id, a run of another workspace, or an Employee Finder run; identical for all three. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - validation_error - unauthenticated - not_found - forbidden - method_not_allowed - idempotency_conflict - idempotency_in_progress - rate_limited - internal_error - run_already_active - search_unavailable - invalid_continuation description: >- Machine-readable error code. Branch on this, not on `message`. message: type: string description: Human-readable explanation. retryAfterSeconds: type: integer description: >- Present on a 429 only: seconds until the workspace may call again (same value as the `Retry-After` header). required: - code - message required: - error '405': description: Method not allowed — see the `Allow` response header. content: application/json: schema: type: object properties: error: type: object properties: message: type: string required: - message required: - error '429': description: >- Rate limit exceeded for this workspace. Retry after the number of seconds in the `Retry-After` header (60). Rate-limited calls are never billed. content: application/json: schema: type: object properties: error: type: object properties: message: type: string required: - message required: - error '500': description: '`internal_error`: the read failed on our side.' content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - validation_error - unauthenticated - not_found - forbidden - method_not_allowed - idempotency_conflict - idempotency_in_progress - rate_limited - internal_error - run_already_active - search_unavailable - invalid_continuation description: >- Machine-readable error code. Branch on this, not on `message`. message: type: string description: Human-readable explanation. retryAfterSeconds: type: integer description: >- Present on a 429 only: seconds until the workspace may call again (same value as the `Retry-After` header). required: - code - message required: - error security: - workspaceApiKey: [] components: schemas: Company: type: object properties: name: type: - string - 'null' linkedinUrl: type: - string - 'null' tagline: type: - string - 'null' description: type: - string - 'null' industry: type: - string - 'null' employeeBand: type: - string - 'null' description: Size band as the source displays it. employeeCount: type: - integer - 'null' description: Exact headcount, when stated. followerCount: type: - integer - 'null' websiteUrl: type: - string - 'null' websiteDomain: type: - string - 'null' headquarters: type: - string - 'null' hqLocality: type: - string - 'null' hqRegion: type: - string - 'null' hqCountry: type: - string - 'null' foundedYear: type: - integer - 'null' companyType: type: - string - 'null' specialties: type: array items: type: string logoUrl: type: 'null' description: >- Always null. Reserved so the shape stays stable: a provider image address is never returned (it is signed, expires, and discloses the viewer). Render `logoImageUrl`. logoImageUrl: type: - string - 'null' description: >- Our own copy of the logo (`/api/images/`, same authentication as this API). Null when the source states no logo or no copy is held. phone: type: - string - 'null' description: >- The company phone. Always null until phone verification is available; reserved so the shape does not change when it is. email: type: - string - 'null' description: >- The company's general contact email: only a generic role address (info@, sales@, …) on the company's own domain, stated by the company, that passed email verification. Null when none is stated or it did not verify. Never a personal address. xUrl: type: - string - 'null' description: >- X (Twitter) profile the company states as its own, as `https://x.com/`. Null when not stated; never constructed from the name. facebookUrl: type: - string - 'null' description: >- Facebook page the company states as its own, as `https://www.facebook.com/`. Null when not stated. instagramUrl: type: - string - 'null' description: >- Instagram profile the company states as its own, as `https://www.instagram.com/`. Null when not stated. youtubeUrl: type: - string - 'null' description: >- YouTube channel the company states as its own, as `https://www.youtube.com/` followed by `@handle`, `channel/…`, `c/…` or `user/…`. Null when not stated. confirmedAt: type: - string - 'null' description: >- When this record was last confirmed against the source. Null when the Company is built only from what a lead or list row observed (no company record). required: - name - linkedinUrl - tagline - description - industry - employeeBand - employeeCount - followerCount - websiteUrl - websiteDomain - headquarters - hqLocality - hqRegion - hqCountry - foundedYear - companyType - specialties - logoUrl - logoImageUrl - phone - email - xUrl - facebookUrl - instagramUrl - youtubeUrl - confirmedAt description: >- The canonical Company for the current employer (same schema as `POST /api/v1/company`). Person: type: - object - 'null' properties: avatarUrl: type: - string - 'null' description: >- Owned image address (`/api/images/`, authenticated). Null ⇒ render initials. fullName: type: - string - 'null' description: The source's own statement of the name. linkedinUrl: type: string description: Canonical profile URL — the identity. Never null. title: type: - string - 'null' description: Title of the primary current position. about: type: - string - 'null' company: $ref: '#/components/schemas/Company' companyName: type: - string - 'null' description: Alias of `company.name`. companyLinkedinUrl: type: - string - 'null' description: Alias of `company.linkedinUrl`. companyLogoUrl: type: - string - 'null' description: Alias of `company.logoImageUrl` (owned). domain: type: - string - 'null' description: >- The company's website domain, else the domain the profile resolver stated. industry: type: - string - 'null' description: Alias of `company.industry`. location: type: - string - 'null' description: The person's own location (never company HQ). department: type: - string - 'null' enum: - Accounting - Administrative - Arts and Design - Business Development - Community & Social Services - Consulting - Customer Success and Support - Education - Engineering - Entrepreneurship - Finance - Healthcare Services - Human Resources - Information Technology - Legal - Marketing - Media and Communication - Military and Protective Services - Operations - Product Management - Program and Project Management - Purchasing - Quality Assurance - Real Estate - Research - Sales description: Source-stated only; never classified from the title. seniority: type: - string - 'null' enum: - In Training - Entry Level - Senior - Strategic - Entry Level Manager - Experienced Manager - Director - Vice President - CXO - Owner / Partner description: Source-stated only; never classified from the title. yearsOfExperience: type: - string - 'null' enum: - Less than 1 year - 1-2 years - 3-5 years - 6-10 years - 11-15 years - 16-20 years - 20+ years description: >- Overlap-free union of stated positions; null when any start is missing or the stated precision leaves it between two buckets. employment: type: array items: $ref: '#/components/schemas/EmploymentEntry' description: Source order; [] when not available. education: type: array items: $ref: '#/components/schemas/EducationEntry' description: Source order; [] when not available. historyStatus: type: object properties: employment: type: string enum: - available - not-yet-available description: >- `not-yet-available`: no source has supplied this history yet (the list is []). `available` with [] means the source supplied an empty history. education: type: string enum: - available - not-yet-available description: >- `not-yet-available`: no source has supplied this history yet (the list is []). `available` with [] means the source supplied an empty history. required: - employment - education required: - avatarUrl - fullName - linkedinUrl - title - about - company - companyName - companyLinkedinUrl - companyLogoUrl - domain - industry - location - department - seniority - yearsOfExperience - employment - education - historyStatus description: >- linkedin mode only: THE canonical Person, present whenever resolution found someone; otherwise null. ErasedRunResult: type: object properties: id: type: string description: Stable id of this delivered result row. position: type: integer description: 0-based delivery position within the run. sourcePage: type: - integer - 'null' description: The source page that delivered the row; null on older rows. erased: type: boolean enum: - true description: 'Removed at the person''s request: no personal data is served.' required: - id - position - sourcePage - erased EmploymentEntry: type: object properties: companyName: type: - string - 'null' companyLinkedinUrl: type: - string - 'null' title: type: - string - 'null' start: $ref: '#/components/schemas/StatedDate' end: $ref: '#/components/schemas/StatedDate' current: type: boolean location: type: - string - 'null' description: Where the position was held, as the source stated it. description: type: - string - 'null' description: The person's own description of the position, as stated. required: - companyName - companyLinkedinUrl - title - start - end - current - location - description EducationEntry: type: object properties: school: type: - string - 'null' schoolLinkedinUrl: type: - string - 'null' degree: type: - string - 'null' field: type: - string - 'null' start: $ref: '#/components/schemas/StatedDate' end: $ref: '#/components/schemas/StatedDate' required: - school - schoolLinkedinUrl - degree - field - start - end StatedDate: type: - object - 'null' properties: year: type: integer month: type: - integer - 'null' description: 1–12, or null when the source stated the year only (never padded). required: - year - month securitySchemes: workspaceApiKey: type: http scheme: bearer description: >- Workspace API key (`loice_sk_` + 48 hex characters), created under Settings → API Keys. Sent as `Authorization: Bearer loice_sk_…`. Invalid, missing, or expired keys are rejected with 401 before any billable work happens. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.