> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbitsearch.com/llms.txt > Use this file to discover all available pages before exploring further. # Search a population > Search everyone at a company or everyone who attended a school. Results arrive while the search runs. A population search is a v3 search whose results are everyone in one population: every current employee of a company, or everyone who attended a school. The search adds people to its results as it finds them. Price the search first with [Price a population](/api/search/population-quote). Starting it reserves the quoted credits. ```bash theme={"dark"} curl -X POST "https://api.orbitsearch.com/v3/search/populations" \ -H "Authorization: Bearer $ORBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "request_id": "a6c1c2f0-4d3e-4b0f-9b3e-2e2a5a4f1c11", "population": { "kind": "company", "id": "1441", "name": "OpenAI" }, "size": 2400, "profile_depth": "partial" }' ``` ## Request body | Field | Type | Default | Description | | ----------------- | --------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------- | | `request_id` | string | generated | Idempotency key. The same `request_id` returns the same search; a different population under the same id returns `409`. | | `population.kind` | `company` or `school` | — | What the population is. | | `population.id` | string | — | The numeric id of the company or school. | | `population.name` | string | — | The company or school name, 1–200 characters. | | `size` | integer | `null` | How many people the population has, when you know it. | | `profile_depth` | `partial` or `full` | `partial` | The depth every person in the population is built to. See [Profile depth](/concepts/search#2-profile-depth). | ## Response The response is a [search snapshot](/api/search/search-status). Poll `GET /v3/search/{search_id}` while `status` is `running`; results are append-only, so every poll returns everyone found so far. Population searches use `include_profile: false`; read a profile with [Read a profile](/api/enrich/read-profile). The snapshot carries a `population` block: | Field | Description | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `kind`, `id`, `name` | The population's subject. | | `size` | The population's size as given, or `null`. | | `profile_depth` | The depth every person is built to. | | `credits_quoted` | The credits reserved when the search started. | | `status` | `running`, `completed`, `completed_with_errors`, `failed` or `cancelled`. The search's own `status` is `completed_with_errors` when the population ends `failed` or `cancelled`. | The search completes when the whole population is in. A person who could not be built ends `failed` and the search ends `completed_with_errors`. ## Billing Orbit reserves the quoted credits when the search starts, settles them as the work completes, and releases what it did not use when the search ends. See [Credits](/concepts/credits). ## Rate limits A population start spends the same rate-limit bucket as `POST /v3/search`. The quote spends the status bucket. ## OpenAPI ````yaml openapi.json POST /v3/search/populations openapi: 3.1.0 info: title: Orbit API version: 3.0.0 description: Search for people and enrich known Orbit profiles. servers: - url: https://api.orbitsearch.com description: Production security: - bearerAuth: [] tags: - name: Search description: Find people and poll search results. - name: Enrich description: Read or enrich known Orbit profiles. - name: Watchers description: Watch a profile on a schedule and read what each run found. - name: Webhooks description: Register endpoints that receive signed event deliveries. paths: /v3/search/populations: post: tags: - Search summary: Search a population description: >- Search everyone at a company or everyone who attended a school. People are added to the results as the search finds them. Reserves the quoted credits. Requires the `search:read` scope. operationId: startPopulationSearch parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PopulationRequest' responses: '200': description: The search completed at once. content: application/json: schema: $ref: '#/components/schemas/SearchSnapshot' '202': description: The search is running. Poll GET /v3/search/{search_id}. content: application/json: schema: $ref: '#/components/schemas/SearchSnapshot' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientCredits' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- A client-generated key for a safe retry. If the body omits `request_id`, Orbit can use this value as the request ID. schema: type: string maxLength: 200 schemas: PopulationRequest: type: object required: - population properties: request_id: type: string maxLength: 200 description: >- Idempotency key. The same request_id returns the same search; a different population under the same id returns 409. population: $ref: '#/components/schemas/PopulationSubject' size: type: integer nullable: true minimum: 0 description: How many people the population has, when you know it. profile_depth: type: string enum: - partial - full default: partial description: The depth every person in the population is built to. SearchSnapshot: type: object required: - search_id - request_id - status - candidate_discovery - profile_depth - include_profile - profile_upgrades_completed - results - created_at - updated_at - links properties: search_id: type: string description: >- Server-generated identifier for this search. Use it to poll the status endpoint. request_id: type: string description: >- The idempotency key from the original request, or a generated value when the request omitted it. status: type: string description: >- Overall search lifecycle. `running` means work is still in progress; poll until the status is terminal. `completed` means every result reached the requested profile depth; a search can complete with an empty results list when nothing matched. `completed_with_errors` means ready results are available but some work failed. `failed` means work failed and no ready results are available. enum: - running - completed - completed_with_errors - failed candidate_discovery: type: boolean description: >- Whether this search runs candidate discovery, as resolved from the request. candidate_discovery_completed: type: boolean description: >- Whether the result list is final. Once true, discovery adds no more results to this search; the results themselves can still be generating or enriching toward the requested depth. For discovery searches this becomes true when clustering completes and every discovered person appears in results. If discovery failed, candidate_discovery_failure explains why. Present only when candidate_discovery is true. provider_results_final: type: boolean description: >- Whether the people-data provider lookup for a supplied phone, email, or address returned its complete owner set. Once true, every owner of that contact is in results with the contacts the provider reported, usually within the first response and before biography work. Discovery by name can still add results until candidate_discovery_completed is true. Present only when candidate_discovery is true and the request carried a phone, email, or address signal. profile_depth: type: string description: The minimum profile depth requested for each ready result. enum: - partial - full include_profile: type: boolean description: Whether readable results embed their Search profile. profile_upgrades_completed: type: boolean description: >- Whether every result in results has reached the requested profile_depth or failed. While candidate_discovery_completed is false, discovery can still add results with new profile work. results: type: array description: >- The people this search has found so far. Results are append-only: a reported result is never removed, and a ready result never regresses. items: $ref: '#/components/schemas/SearchResult' discovered_sources: type: array description: >- Candidate Discovery source receipts that have not yet been assigned to a result. Present when candidate_discovery is true. items: $ref: '#/components/schemas/CandidateDiscoverySource' candidate_discovery_failure: $ref: '#/components/schemas/Failure' description: Why candidate discovery failed. Present only when discovery failed. population: $ref: '#/components/schemas/Population' query_intent: allOf: - $ref: '#/components/schemas/QueryIntent' description: Present when the search parsed a plain-English query. created_at: type: string format: date-time description: When the search was created. updated_at: type: string format: date-time description: When the snapshot last changed. links: type: object required: - status properties: status: type: string description: Relative URL for the search status endpoint. billing: $ref: '#/components/schemas/OperationBilling' description: >- Credits held and spent for this search. The final consumedCredits is the full charge once status is settled. PopulationSubject: type: object required: - kind - id - name properties: kind: type: string enum: - company - school description: >- What the population is: the current employees of a company, or the alumni of a school. id: type: string description: The numeric id of the company or school. name: type: string minLength: 1 maxLength: 200 description: The company or school name. SearchResult: type: object required: - profile_id - status - generation_level - sources properties: profile_id: type: string description: >- Stable identifier for this person. Use it with the profile endpoints. status: type: string description: >- Result lifecycle. `generating` means candidate discovery found this person but no readable profile exists yet; it appears only on candidate discovery results. `enriching` means a readable profile exists but is below the requested depth. `ready` means the profile reached the requested profile_depth. `failed` means this result cannot reach the requested depth; failure explains why. Statuses only move forward. enum: - generating - enriching - ready - failed generation_level: description: >- The stored generation level of this profile: 1 contains Orbit identity data, 2 adds LinkedIn enrichment, 3 adds web, social, and OSINT enrichment. A `partial` depth requires at least level 2 and a `full` depth requires level 3. Null until the profile is first published. oneOf: - type: integer minimum: 1 - type: 'null' sources: type: array description: >- The origins that produced this result. This field does not contain source receipts. items: type: string enum: - search - candidate_discovery candidate_sources: type: array description: >- Candidate Discovery source receipts assigned to this result. Assigned receipts remain stable when the result becomes ready. items: $ref: '#/components/schemas/CandidateDiscoverySource' preview: type: object additionalProperties: true description: >- Lightweight search preview built from the data Search returned for this person, such as name, avatar, location, headline, and generation level. Known-search results carry it with either include_profile value. profile: $ref: '#/components/schemas/SearchProfile' description: >- The profile embedded in a readable result when include_profile is true: identity fields, contact fields, and generated sections. Read GET /v3/enrich/{profile_id} for the image gallery and source links. failure: $ref: '#/components/schemas/Failure' CandidateDiscoverySource: type: object additionalProperties: false required: - link - title - sourceImage properties: link: type: string format: uri description: URL of the discovered source page. title: type: string description: Display title of the source page or site. sourceImage: type: string format: uri description: URL of the favicon for the site that hosts the source page. Failure: type: object required: - code - message - retryable - reason properties: code: type: string message: type: string retryable: type: boolean reason: type: string suggested_inputs: type: array items: type: string Population: type: object required: - kind - id - name - size - profile_depth - credits_quoted - status description: >- Present on population searches: the subject, the depth, the reserved credits and where the search is. properties: kind: type: string enum: - company - school id: type: string name: type: string size: type: integer nullable: true description: The population's size as given, or null. profile_depth: type: string enum: - partial - full description: The depth every person is built to. credits_quoted: type: integer description: The credits reserved when the search started. status: type: string enum: - running - completed - completed_with_errors - failed - cancelled description: >- Where the population search is. The search's own status is running while this is running, completed when this is completed, and completed_with_errors when this is completed_with_errors, failed or cancelled. QueryIntent: type: object required: - organizations - schools - person_named description: What the search understood from a plain-English query. properties: organizations: type: array items: type: string description: The companies the query names. schools: type: array items: type: string description: The schools the query names. person_named: type: boolean description: Whether the query names a specific person. OperationBilling: type: object description: >- Credits held and spent for the billing operation behind this request. Poll until status is settled to read the final consumedCredits. required: - id - pricingVersion - reservedCredits - consumedCredits - releasedCredits - heldCredits - status properties: id: type: string format: uuid description: The billing operation behind this request. pricingVersion: type: string description: The pricing catalog version this operation settles under. reservedCredits: type: integer minimum: 0 description: The credits held for this operation. consumedCredits: type: integer minimum: 0 description: The credits charged so far. releasedCredits: type: integer minimum: 0 description: The credits returned to your balance. heldCredits: type: integer minimum: 0 description: >- The credits still held: reservedCredits less consumedCredits and releasedCredits. status: type: string enum: - open - settled description: >- open while the operation can still charge, and settled once its charge is final. ErrorResponse: type: object required: - status - error properties: status: type: string enum: - failed error: type: object required: - code - message properties: code: type: string message: type: string requiredCredits: type: integer minimum: 0 description: >- Credits required when the error is developer_api_credits_insufficient. remainingCredits: type: integer minimum: 0 description: >- Available credits when the error is developer_api_credits_insufficient. SearchProfile: type: object description: >- The profile that Search embeds in a readable result: identity fields, contact fields, employment domains, and generated sections. Optional fields appear when they have values. Read GET /v3/enrich/{profile_id} for the full public profile with the image gallery and source links. required: - id - generationLevel - avatarUrl - verified - sections additionalProperties: true properties: id: 8bd53814-e746-4eb2-998d-6f1c04b50489 generationLevel: aab56b59-b14b-4264-8f23-e02492f0b301 displayName: d98a52b9-319b-4d8a-a16f-16a6b448ddf7 personName: d528ced7-3181-4ecd-a28d-aa1f9c20f22c aliases: e9d3b293-02e1-479d-baaf-d97eb8c552fa avatarUrl: 4a0596e8-5712-4445-8886-46bc0b2aaa44 profileUrl: 510728b3-271e-41bf-a97b-b79bc9632786 slug: af81c71a-9853-4d56-a2ac-9d03ac48377b category: 585f3590-a662-4999-b39a-0088c592c2cb verified: eda35ebb-bc3b-4d08-b04a-a7a04acf6e55 location: 3594fcda-5395-49a1-a610-fe24a4da8ddd headline: 7e02b451-1e4d-43b0-a6a6-685b7d084072 sections: type: object description: >- Generated profile sections, such as bio, jobs, and education. Each section carries its content fields. Read GET /v3/enrich/{profile_id} for the image gallery and source links. required: - socials properties: bio: $ref: '#/components/schemas/SearchProfileBioSection' basic: $ref: '#/components/schemas/SearchProfileSection' personalLife: $ref: '#/components/schemas/SearchProfileSection' socials: $ref: '#/components/schemas/SearchProfileItemsSection' jobs: $ref: '#/components/schemas/SearchProfileSection' education: $ref: '#/components/schemas/SearchProfileSection' passions: $ref: '#/components/schemas/SearchProfileSection' worldview: $ref: '#/components/schemas/SearchProfileSection' accomplishments: $ref: '#/components/schemas/SearchProfileSection' controversies: $ref: '#/components/schemas/SearchProfileSection' bestQualities: $ref: '#/components/schemas/SearchProfileSection' netWorth: $ref: '#/components/schemas/SearchProfileSection' eventsTimeline: $ref: '#/components/schemas/SearchProfileSection' portfolio: $ref: '#/components/schemas/SearchProfileSection' families: $ref: '#/components/schemas/SearchProfileSection' researchPapers: $ref: '#/components/schemas/SearchProfileItemsSection' githubRepos: $ref: '#/components/schemas/SearchProfileItemsSection' mediaCredits: $ref: '#/components/schemas/SearchProfileItemsSection' musicCredits: $ref: '#/components/schemas/SearchProfileItemsSection' books: $ref: '#/components/schemas/SearchProfileItemsSection' emails: fb920656-e5af-4671-a528-a7045dac4d85 emailDetails: type: array description: >- One summary for each published email address: its type, the employer behind the domain, and whether mail reaches it, when available. items: type: object required: - email - type - typeBasis - verification additionalProperties: true properties: email: type: string format: email type: type: string enum: - personal - work - unknown description: '`unknown` means the evidence on hand leaves the type open.' typeBasis: type: string enum: - consumer_domain - provider_free_domain - employment_domain - employment_name - provider_employer_claim - role_address - academic_domain - conflicting_evidence - insufficient_evidence description: The evidence behind `type`. employer: type: object required: - association additionalProperties: true description: The company that owns the domain, when one is known. properties: companyName: type: string companyDomain: type: string association: type: string enum: - current - former - unknown description: >- Whether the person still works at the company. `unknown` means a company was reported with no tenure. verification: type: object required: - status additionalProperties: true properties: status: type: string enum: - deliverable - undeliverable - risky - unverified description: >- `risky` means the domain accepts every address or the check was weak. `unverified` means the address was reported with no check. verifiedAt: type: string format: date-time description: When the check ran. catchAllDomain: type: boolean description: Whether the domain accepts every address. employmentDomains: type: array description: >- Employer domains from the profile's employment history, with whether each role is current, when available. items: type: object required: - isCurrent additionalProperties: true properties: companyName: type: string domain: type: string isCurrent: type: boolean description: Whether this role is current. phoneNumbers: 3c3dfe0d-53fd-490a-aadf-9d26c45c7e36 phoneDetails: type: array description: What providers reported about each phone number, when available. items: type: object required: - phoneNumber - type additionalProperties: true properties: phoneNumber: type: string type: type: string enum: - mobile - landline - voip - unknown isConnected: type: boolean firstReported: type: number lastReported: type: number addresses: 807f61b6-ff5c-4270-b407-121081b8e0fa SearchProfileBioSection: oneOf: - type: 'null' - type: object description: The generated bio text. required: - bio additionalProperties: true properties: bio: type: string SearchProfileSection: oneOf: - type: 'null' - $ref: '#/components/schemas/SearchProfileItemsSection' SearchProfileItemsSection: type: object description: >- A generated section with its items. Each item carries its content fields. required: - items additionalProperties: true properties: items: type: array items: type: object additionalProperties: true responses: BadRequest: description: The request is not valid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: The API key is missing or not valid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InsufficientCredits: description: >- The available API credit balance cannot cover the requested work. Top up before retrying. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: The API key does not have the required scope. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Conflict: description: The request ID was already used with different inputs. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' RateLimited: description: The API key exceeded a rate limit. headers: Retry-After: description: Seconds to wait before another request. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Orbit API key description: Use an Orbit API key from the developer dashboard. ````