> ## 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.

# Price a population search

> See what it costs to search everyone at a company or everyone who attended a school before you start.

A population search returns everyone in one population: every current employee of a company, or everyone who attended a school. Price it first, then start it with [Search a population](/api/search/population).

```bash theme={"dark"}
curl -X POST "https://api.orbitsearch.com/v3/search/populations/quote" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "population": { "kind": "company", "id": "1441", "name": "OpenAI" },
    "size": 2400,
    "profile_depth": "partial"
  }'
```

## Request body

| Field             | Type                  | Default   | Description                                                                                            |
| ----------------- | --------------------- | --------- | ------------------------------------------------------------------------------------------------------ |
| `population.kind` | `company` or `school` | —         | What the population is: the current employees of a company, or the alumni of a school.                 |
| `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. A full population costs more than a partial one. |

## Response

| Field             | Description                                                                                     |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| `population`      | The subject you asked about.                                                                    |
| `size`            | The size as given, or `null`.                                                                   |
| `profile_depth`   | The depth the quote priced.                                                                     |
| `credits`         | The whole cost of the search, as one number. Orbit reserves this amount when the search starts. |
| `max_people`      | The most people one population search covers (5,000).                                           |
| `pricing_version` | The [pricing catalog](/concepts/credits) version the quote used.                                |


## OpenAPI

````yaml openapi.json POST /v3/search/populations/quote
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/quote:
    post:
      tags:
        - Search
      summary: Price a population search
      description: >-
        What it costs to search everyone at a company or everyone who attended a
        school. Requires the `search:read` scope.
      operationId: quotePopulationSearch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PopulationQuoteRequest'
      responses:
        '200':
          description: The quote.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PopulationQuote'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    PopulationQuoteRequest:
      type: object
      required:
        - population
      properties:
        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.
    PopulationQuote:
      type: object
      required:
        - population
        - size
        - profile_depth
        - credits
        - max_people
        - pricing_version
      properties:
        population:
          $ref: '#/components/schemas/PopulationSubject'
        size:
          type: integer
          nullable: true
          description: The population's size as given, or null.
        profile_depth:
          type: string
          enum:
            - partial
            - full
          description: The depth the quote priced.
        credits:
          type: integer
          description: >-
            The whole cost of the search, as one number. Reserved when the
            search starts.
        max_people:
          type: integer
          description: The most people one population search covers.
        pricing_version:
          type: string
          description: The pricing catalog version the quote used.
    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.
    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.
  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'
    Forbidden:
      description: The API key does not have the required scope.
      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.

````