> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tako.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search people

> Build a list of people from filters

> [!NOTE]
>
> The Enrichment API is in **beta**. Its request and response shapes can change.

Screens people by role, place and employer. See the **[Search guide](https://docs.tako.com/documentation/integrating-tako/enrichment/search.md)** for the filters.

## Notes

* To authenticate, send your [Tako API key](https://tako.com/console/api-keys) in the `X-API-Key` header. Store it as an environment variable rather than hardcoding it.
* The response carries its list as a card. To get the rows, pass the card's `webpage_url` to [Contents](https://docs.tako.com/api-reference/contents.md), or set `include_contents` on this request.
* Premium fields are withheld. Export the card through [Contents](https://docs.tako.com/api-reference/contents.md) with `premium` set to `true` to reveal them.
* The schema `PersonListField` lists the card's fields. See [What a list holds](https://docs.tako.com/documentation/integrating-tako/enrichment/overview.md#what-a-list-holds).
* Each successful request bills one request. See [Pricing](https://docs.tako.com/documentation/integrating-tako/enrichment/overview.md#pricing).


## OpenAPI

````yaml POST /v1/people/search
openapi: 3.1.0
info:
  title: Knowledge Search API
  version: 1.0.0
servers:
  - url: https://tako.com/api/
    description: Tako Production API Server
security: []
paths:
  /v1/people/search:
    post:
      tags:
        - tako
      summary: Search people (beta)
      description: >-
        Screen employees by role, employer, employer profile and location.
        Email, phone and LinkedIn identifiers narrow the screen to the people
        they name, beside at least one other filter, up to 50 values in all.
        Returns the list as one Tako card, with its total and the filters
        applied. Set include_contents to inline the card's first rows. For the
        rest of the list and for premium fields, call POST /api/v1/contents with
        the card's webpage_url, an offset and premium=true.
      operationId: searchPeople
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonSearchRequest'
      responses:
        '200':
          description: Search people (beta)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonSearchResponse'
        '400':
          description: >-
            A filter or input that can't run. field names the request field,
            code says why, and suggestions holds values to use instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichInputError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '402':
          description: >-
            Payment required. The PAYG API-credit balance is empty or depleted
            (error_type, error_message, balance_cents).
          content:
            application/json:
              schema:
                properties:
                  error_type:
                    type: string
                  error_message:
                    type: string
                  balance_cents:
                    type: integer
                type: object
                required:
                  - error_type
                  - error_message
                  - balance_cents
        '403':
          description: >-
            The account may not call this endpoint: it needs access to People
            Data Labs data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '429':
          description: >-
            Too many requests. With error_type RATE_LIMIT_EXCEEDED, the request
            hit a rate limit: retry after the interval in the Retry-After
            header. With error_type BUDGET_EXCEEDED, the API key or its owner
            has used a spend budget: do not retry automatically. A budget
            response carries the header x-should-retry: false, and Retry-After
            with the seconds until the budget resets, except for a total budget.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/RateLimitExceededError'
                  - $ref: '#/components/schemas/BudgetExceededError'
        '503':
          description: >-
            The screen or a lookup it needs didn't finish in time or failed, its
            index isn't available, or the result's card couldn't be saved. Try
            again later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
        - apiKey: []
components:
  schemas:
    PersonSearchRequest:
      properties:
        include_contents:
          type: boolean
          title: Include Contents
          description: >-
            Inline the card's rows in the response, under card.content. Premium
            fields are never inlined: pass the card's webpage_url to POST
            /api/v1/contents with premium=true to unlock them.
          default: false
        max_rows:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max Rows
          description: >-
            Maximum number of rows to inline when include_contents is true. Omit
            it and Tako uses your account's inline row cap. Tako clamps a larger
            value to the card's export_pricing.max_rows_ceiling (at most
            100,000). Every inlined row is billed at the POST /api/v1/contents
            rate. For the rest of the list, call POST /api/v1/contents with the
            card's webpage_url and an offset. A card export can hold up to
            100,000 rows. Don't read a large export directly into a model's
            context: at about 15 tokens per row, 10,000 rows cost about 150,000
            tokens. Write the export to a file, on disk or in memory, and have
            the agent parse it with code. Give the model only the rows or
            results it needs.
        content_format:
          $ref: '#/components/schemas/ContentsFormat'
          description: >-
            Serialization for the inlined rows: 'json_compact', 'json_records',
            'csv', or 'card_json'.
          default: json_compact
        role:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 20
            - type: 'null'
          title: Role
          description: Title, seniority or function phrases, such as 'head of sales'.
        company_ids:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 100
            - type: 'null'
          title: Company Ids
          description: Employer ids from the companies endpoints.
        company_domains:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 100
            - type: 'null'
          title: Company Domains
          description: Employer websites.
        person_country:
          anyOf:
            - type: string
            - type: 'null'
          title: Person Country
        person_region:
          anyOf:
            - type: string
            - type: 'null'
          title: Person Region
        person_metro:
          anyOf:
            - type: string
            - type: 'null'
          title: Person Metro
        person_town:
          anyOf:
            - type: string
            - type: 'null'
          title: Person Town
          description: Needs person_country or person_region beside it.
        company_industry:
          anyOf:
            - type: string
            - type: 'null'
          title: Company Industry
          description: >-
            The employer's industry, by name or id, as companies/search takes
            it.
        company_min_employees:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Company Min Employees
        company_max_employees:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Company Max Employees
        company_funding_stages:
          anyOf:
            - items:
                type: string
                enum:
                  - angel
                  - convertible_note
                  - corporate_round
                  - debt_financing
                  - equity_crowdfunding
                  - grant
                  - initial_coin_offering
                  - non_equity_assistance
                  - post_ipo_debt
                  - post_ipo_equity
                  - post_ipo_secondary
                  - pre_seed
                  - private_equity
                  - product_crowdfunding
                  - secondary_market
                  - seed
                  - series_a
                  - series_b
                  - series_c
                  - series_d
                  - series_e
                  - series_f
                  - series_g
                  - series_h
                  - series_i
                  - series_j
                  - series_unknown
                  - undisclosed
              type: array
            - type: 'null'
          title: Company Funding Stages
          description: The employer's latest funding stages.
        company_startups:
          type: boolean
          title: Company Startups
          description: >-
            Employers that are startups: private companies founded in the last
            ten years, of a startup type, that raised a venture round or have at
            most 500 employees.
          default: false
        linkedin_urls:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 50
            - type: 'null'
          title: Linkedin Urls
          description: LinkedIn profile URLs.
        emails:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 50
            - type: 'null'
          title: Emails
        phones:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 50
            - type: 'null'
          title: Phones
      additionalProperties: false
      type: object
      title: PersonSearchRequest
      description: >-
        A screen of employees. Contact identifiers narrow it to the people they
        name, beside at least one

        other filter.
    PersonSearchResponse:
      properties:
        card:
          anyOf:
            - $ref: '#/components/schemas/TakoCard'
            - type: 'null'
          description: >-
            The list as a Tako card: embed it, inline its rows with
            include_contents, or pass its webpage_url to POST /api/v1/contents
            for every row (with an offset) and for premium fields
            (premium=true). `PersonListField` names its fields. Null when
            nothing matched.
        total:
          type: integer
          title: Total
        total_is_lower_bound:
          type: boolean
          title: Total Is Lower Bound
          description: >-
            True when total is the count cap (500), not an exact count. POST
            /api/v1/contents with the card's webpage_url reads past it.
        applied:
          items:
            type: string
          type: array
          title: Applied
          description: The filters the screen ran, with their resolved values.
        unresolved:
          items:
            type: string
          type: array
          title: Unresolved
          description: Inputs that named nothing, as field=value.
        failed:
          items:
            type: string
          type: array
          title: Failed
          description: >-
            Inputs whose lookup failed or timed out, as field=value: retry them.
            Not a miss.
          default: []
        notes:
          items:
            type: string
          type: array
          title: Notes
          default: []
      type: object
      required:
        - card
        - total
        - total_is_lower_bound
        - applied
        - unresolved
      title: PersonSearchResponse
    EnrichInputError:
      properties:
        error_message:
          type: string
          title: Error Message
        error_type:
          $ref: '#/components/schemas/APIErrorType'
          default: BAD_REQUEST
        code:
          type: string
          title: Code
        field:
          type: string
          title: Field
        suggestions:
          items:
            type: string
          type: array
          title: Suggestions
          default: []
      type: object
      required:
        - error_message
        - code
        - field
      title: EnrichInputError
      description: >-
        Input the API can't run. code is a list-screen error code (such as
        unknown_industry), or one of

        invalid_body (the body isn't valid JSON), invalid_value, no_filters,

        contacts_need_a_filter and unavailable_filter. field is the request
        field at fault, or "" for an

        error about the whole request. suggestions holds near-miss values to use
        instead.
    BaseAPIError:
      properties:
        error_message:
          type: string
          title: Error Message
        error_type:
          $ref: '#/components/schemas/APIErrorType'
      type: object
      required:
        - error_message
        - error_type
      title: BaseAPIError
    RateLimitExceededError:
      properties:
        error_message:
          type: string
          title: Error Message
        error_type:
          $ref: '#/components/schemas/APIErrorType'
          default: RATE_LIMIT_EXCEEDED
      type: object
      required:
        - error_message
      title: RateLimitExceededError
    BudgetExceededError:
      properties:
        error_message:
          type: string
          title: Error Message
        error_type:
          $ref: '#/components/schemas/APIErrorType'
          default: BUDGET_EXCEEDED
        budget_scope:
          type: string
          enum:
            - api_key
            - member
          title: Budget Scope
          description: >-
            api_key when the key's own budget is used up; member when its
            owner's budget is.
        budget_cents:
          type: integer
          title: Budget Cents
          description: The budget amount, in cents.
        period:
          type: string
          enum:
            - day
            - week
            - month
            - total
          title: Period
          description: The budget period, on UTC boundaries.
        resets_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Resets At
          description: >-
            When the budget resets and requests resume, or null for a total
            budget.
      type: object
      required:
        - error_message
        - budget_scope
        - budget_cents
        - period
        - resets_at
      title: BudgetExceededError
      description: >-
        429: the API key or its owner has used a spend budget for the current
        period.
    ContentsFormat:
      type: string
      enum:
        - csv
        - json_records
        - json_compact
        - card_json
      title: ContentsFormat
      description: >-
        Serialization of tabular (Tako card) data. Web content is always raw
        text

        and carries no content format (content_format is null).
    TakoCard:
      properties:
        card_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Card Id
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        semantic_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Semantic Description
        webpage_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Webpage Url
        image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Url
        embed_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Embed Url
        sources:
          anyOf:
            - items:
                $ref: '#/components/schemas/TakoCardSource'
              type: array
            - type: 'null'
          title: Sources
        methodologies:
          anyOf:
            - items:
                $ref: '#/components/schemas/KnowledgeCardMethodology'
              type: array
            - type: 'null'
          title: Methodologies
        source_indexes:
          anyOf:
            - items:
                $ref: '#/components/schemas/TakoSourceIndex'
              type: array
            - type: 'null'
          title: Source Indexes
        card_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Card Type
        relevance:
          anyOf:
            - $ref: '#/components/schemas/KnowledgeCardRelevance'
            - type: 'null'
          description: >-
            Tako's relevance label for this card, from the same ladder the flat
            `results` relevance uses. On `effort: deep` an LLM scores cards as
            integers 1 to 5, so a 5 is High and a 4 is Medium. A card the LLM
            leaves unscored keeps its continuous retrieval score and can be High
            below 5. Other efforts score continuously and can label the same
            card higher.
        content:
          anyOf:
            - $ref: '#/components/schemas/ResultContent'
            - type: 'null'
        exportable:
          type: boolean
          title: Exportable
          description: >-
            Whether the /contents endpoint can download this card's data. false
            means the export is not available; use the card's chart and inline
            preview instead. true means the export is eligible but not
            guaranteed; the /contents endpoint can still return 403, so fall
            back to the preview on error.
          default: false
        relevance_score:
          anyOf:
            - type: number
            - type: 'null'
          title: Relevance Score
          description: >-
            Numeric relevance of this card to the query on a 1.0-5.0 scale (5.0
            = exact match; higher is more relevant). Only populated for entitled
            accounts; null otherwise.
        nodes:
          anyOf:
            - items:
                $ref: '#/components/schemas/TakoCardNode'
              type: array
            - type: 'null'
          title: Nodes
          description: >-
            Graph nodes (entities and metrics) behind this card. The response
            includes them by default. Absent for web-only cards or when node
            resolution was not available. Use each id with /v1/graph/node/{id}
            for full detail (aliases, subtype), or pass ids in
            sources.data.node_ids to pin these nodes in future searches.
        metric_definitions:
          anyOf:
            - items:
                $ref: '#/components/schemas/MetricDefinition'
              type: array
            - type: 'null'
          title: Metric Definitions
          description: >-
            Definitions of the metrics this card displays (name + definition).
            Null when no displayed metric has a definition available.
        data_freshness:
          anyOf:
            - $ref: '#/components/schemas/DataFreshness'
            - type: 'null'
          description: >-
            Freshness dates for the card's data: where the data ends
            (coverage_end), the same point as a full date (data_as_of,
            deprecated), and the last refresh date (last_updated). Null when no
            date is available.
        placeholder:
          anyOf:
            - $ref: '#/components/schemas/PlaceholderInfo'
            - type: 'null'
          description: >-
            Set when the card is a placeholder: it carries its title and no data
            points, because its source charges for each request and this
            response didn't include that source's data. A search returns a
            placeholder when the request sets variable_cost to false, for every
            request paid through the Machine Payments Protocol (MPP), and for an
            account that isn't served variable-cost data. Null on every card
            that carries its data.
      type: object
      title: TakoCard
      description: |-
        A Tako knowledge card on the search and answer surfaces. It carries a
        `content` download descriptor.
    APIErrorType:
      type: string
      enum:
        - BAD_REQUEST
        - AUTHENTICATION_ERROR
        - INTERNAL_SERVER_ERROR
        - RELEVANT_RESULTS_NOT_FOUND
        - RATE_LIMIT_EXCEEDED
        - PAYMENT_REQUIRED
        - REQUEST_TIMEOUT
        - FORBIDDEN
        - NOT_FOUND
        - SERVICE_UNAVAILABLE
        - SERVICE_OVERLOADED
        - UNSUPPORTED_CONTENT_FORMAT
        - PLACEHOLDER_CARD
        - VARIABLE_COST_NOT_REQUESTED
        - BUDGET_EXCEEDED
        - COST_CAP_EXCEEDED
      title: APIErrorType
    TakoCardSource:
      properties:
        source_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Name
          description: The name of the source
          examples:
            - S&P Global
            - The World Bank
        source_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Description
          description: The description of the source
        source_index:
          $ref: '#/components/schemas/TakoSourceIndex'
          description: The index of the source
          examples:
            - data
            - web
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          description: The URL of the source
          examples:
            - https://xignite.com
        source_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Text
          description: >-
            Raw excerpts retrieved from the source page — the unmodified web
            content that grounded the answer. Set for `web` sources; null for
            `data` sources.
      type: object
      required:
        - source_index
      title: TakoCardSource
      description: |-
        A source that backs a TakoCard on the SDK surfaces. It uses the
        {data, web} TakoSourceIndex taxonomy.
    KnowledgeCardMethodology:
      properties:
        methodology_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Methodology Name
          description: The name of the methodology
          examples:
            - Where the Data Comes From - S&P Global
        methodology_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Methodology Description
          description: >-
            A concise, one-sentence summary of the methodology: the source and
            what it measures. When no concise summary is available, this carries
            the full methodology text.
          examples:
            - >-
              Financial metrics standardized by S&P Global from company
              regulatory filings, press releases, and restatements.
      type: object
      required:
        - methodology_name
        - methodology_description
      title: KnowledgeCardMethodology
    TakoSourceIndex:
      type: string
      enum:
        - data
        - web
      title: TakoSourceIndex
      description: |-
        Public source taxonomy for the SDK card surfaces (v3 search, v1 answer,
        agent). It is symmetric with the request taxonomy {data, web}.
    KnowledgeCardRelevance:
      type: string
      enum:
        - High
        - Medium
        - Low
      title: KnowledgeCardRelevance
    ResultContent:
      properties:
        content_format:
          anyOf:
            - $ref: '#/components/schemas/ContentsFormat'
            - type: 'null'
          description: >-
            Serialization of the returned card data: 'csv', 'json_records',
            'json_compact', or 'card_json'. Null for web text (always returned
            as raw text) and for a quote-only response (nothing was serialized).
        cost:
          type: number
          title: Cost
          description: >-
            Price of this item in USD. On a /contents response this is the
            amount actually billed. On a quote_only response it is a prospective
            /contents export price, because Tako fetched nothing and billed
            nothing. On a search or answer downloadable card it is also a
            prospective price, unless Tako inlined rows for the card; then it is
            the amount this response billed for the card. Use export_pricing on
            its own to price a /contents export of the same card. Do not add
            this value to that result: they are two prices for the same rows,
            not two charges.
          default: 0
        data:
          anyOf:
            - type: string
            - type: 'null'
          title: Data
          description: >-
            Inline payload as text: card data serialized to CSV, or a web page's
            extracted text. Set only for the 'csv' card format and for web text;
            null otherwise.
        records:
          anyOf:
            - items:
                additionalProperties:
                  anyOf:
                    - type: string
                    - type: number
                    - type: integer
                    - type: boolean
                    - items:
                        additionalProperties: true
                        type: object
                      type: array
                    - type: 'null'
                type: object
              type: array
            - type: 'null'
          title: Records
          description: >-
            Inline card data as verbose JSON: a list of row objects keyed by
            column name. Set only when content_format is 'json_records'.
        dataset:
          anyOf:
            - $ref: '#/components/schemas/TakoDataset'
            - type: 'null'
          description: >-
            Inline card data as a compact TakoDataset (typed column headers plus
            positional row arrays). Set only when content_format is
            'json_compact'.
        card_data:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Card Data
          description: >-
            Inline card data as a card-type-specific JSON object. The
            'card_type' field inside the object names its shape. Set only when
            content_format is 'card_json'. Tako truncates the record rows in the
            object to 'max_rows', the same cap every other format takes, and
            bills the rows it returns. A card whose record array is unbounded
            caps that array at the platform export ceiling and reports
            'truncated': true. The payload then also carries the true count for
            its record array. Card types without a card_json shape return 422 on
            /contents and fall back to 'json_compact' on search and answer
            include_contents.
        card_data_schema:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Card Data Schema
          description: >-
            JSON Schema for the object in 'card_data'. Read it to learn the
            shape of the payload without parsing the payload. Tako sets this
            whenever content_format is 'card_json'. It is also set in 'url'
            delivery mode and on a Contents quote, where 'card_data' is null and
            the shape is all Tako returns. A search or answer card that you did
            not ask to inline carries a price but no schema. The 'title' field
            and the 'card_type' default inside the schema name the shape. The
            schema describes the payload type, so 'card_data' can omit a field
            the schema declares: Tako drops a measure the provider did not
            supply. Null for every other content_format and for web text.
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          description: >-
            Presigned download URL for the content, returned in 'url' delivery
            mode. Null for inline delivery and for quotes; pair with expires_at.
        expires_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Expires At
          description: >-
            ISO-8601 timestamp after which the presigned url stops working. Null
            whenever url is null.
        total_rows:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Rows
          description: >-
            Total number of rows in the card's data, independent of how many
            rows were returned. Compare with the rows returned to tell whether a
            larger max_rows returns more. A card that lists a capped slice of a
            larger set, such as the 30 soonest-closing of 330 open
            solicitations, has only that slice as its data, so total_rows is 30
            and total_matching gives the set's size. On an agent run card, it's
            set for a card whose rows are stored with the card, such as a people
            list, and null for other agent run cards. On a search or answer card
            that returns no rows, it's set when the card can hold premium
            values, and gives the rows a /contents export of the card returns. A
            list of companies or people that match a name or a set of filters,
            such as fintechs in London, shows the top of a search its /contents
            export runs again, so on a search or answer card, returned rows or
            not, total_rows is the most rows that export returns, and truncated
            is true. Null for web text.
        total_matching:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Matching
          description: >-
            Size of the whole set behind a card that lists a capped slice of it,
            such as 330 for a card listing the 30 soonest-closing of 330 open
            solicitations. It's the count the card's description states, and
            it's the same on every content format. A larger max_rows doesn't
            return more of that set. Tako reports it for the cards that list
            such a slice: open solicitations, international tenders, a federal
            agency's contracts, and a company's news. Null when the card's rows
            are the whole set, when Tako doesn't count the set (truncated is
            still true), and for web text.
        truncated:
          type: boolean
          title: Truncated
          description: >-
            True when the card has more rows than Tako returned. Tako caps a
            card at the request max_rows or at the card's max_rows_ceiling (at
            most 100,000), and then total_rows is larger than the rows returned.
            It's also true when the card itself lists a capped slice of a larger
            set; then total_matching gives the set's size when Tako counts it.
            On a search or answer response, it's also true when a /contents
            export of a list card returns more rows than the card shows, and
            then total_rows counts the export's rows. An inline /contents export
            that omits max_rows returns up to 2,000 rows. On a search or answer
            response, all cards share a budget of 2,000 billable rows and a
            budget of 20,000 inline rows, both spent in card order, so a later
            card can return fewer rows than max_rows asked for. A card the
            billable budget can no longer pay for still returns a small preview.
            A card that arrives after the inline budget runs out returns no
            inline rows, and its export_pricing still prices a /contents export
            of them.
          default: false
        export_pricing:
          anyOf:
            - $ref: '#/components/schemas/ExportPricing'
            - type: 'null'
          description: >-
            Rate card for a downloadable card CSV, so a caller can compute a
            full export's cost before fetching. Null for web text and other
            non-downloadable content.
        manifest:
          anyOf:
            - items:
                $ref: '#/components/schemas/ColumnDescriptor'
              type: array
            - type: 'null'
          title: Manifest
          description: >-
            Per-column metadata, one entry per exported column, in column order:
            entry i describes column i (CSV header i, json_records key i, or
            dataset.columns[i]). Each entry carries name (the column header),
            dtype, unit, metric, entity, and premium_class. On an agent run
            card, it's set wherever total_rows is. Null for web text and for
            other quotes that carry no tabular columns.
        premium:
          type: boolean
          title: Premium
          description: >-
            True when this item's premium cells are revealed: a /contents
            response to premium=true. False on every search and answer card and
            on a /contents response without the flag. There, a withheld premium
            cell reads [premium: withheld] in CSV and is null in JSON formats,
            and redacted_cells says which rows held a value.
          default: false
        premium_rows:
          anyOf:
            - additionalProperties:
                type: integer
              type: object
            - type: 'null'
          title: Premium Rows
          description: >-
            Per premium class ('company_record', 'person_contact'), the number
            of distinct records that the delivered rows hold a value for in a
            column of that class, whether revealed or withheld: one per company
            for 'company_record' and one per person for 'person_contact'. A row
            whose record can't be identified counts as its own record. Multiply
            by export_pricing.premium_row_cpm_usd[class] / 1000 to price the
            premium part of an export before asking for it. A row with cells of
            two classes counts in each. Empty for a card with no premium
            columns; null for web text. On an agent run card, it counts every
            row of the card, so a premium=true export of all total_rows rows
            bills exactly these records when total_rows is within
            max_rows_ceiling. On a search or answer card that returns no rows,
            it counts the rows the card shows, and it's null for a card that
            can't hold a premium value. When truncated is true there, an export
            reads more rows than the card shows, so these counts are a
            preview's: ask /contents with quote_only for the premium price. It's
            set wherever total_rows is.
        redacted_cells:
          anyOf:
            - additionalProperties:
                items:
                  type: integer
                type: array
              type: object
            - type: 'null'
          title: Redacted Cells
          description: >-
            Column header to the 0-based positions, among the delivered rows,
            whose premium value was withheld. Present only when a premium cell
            was withheld; null when premium=true, when nothing was withheld, and
            for web text. Positions index the delivered rows: CSV data rows in
            order, json_records entries, or dataset.rows. In CSV, the same cells
            read [premium: withheld]; a premium cell with no value is blank.
        delivery:
          type: string
          enum:
            - quote
            - inline
            - url
          title: Delivery
          description: >-
            How Tako delivered the content. 'quote' means Tako delivered
            nothing, and cost is the price of a later POST /v1/contents export.
            'inline' means the content is in data, records, dataset, or
            card_data. 'url' means you download it from url before expires_at.
          readOnly: true
      type: object
      title: ResultContent
      description: >-
        Describes the downloadable content behind a result.


        Pricing: for a Tako card CSV export, the charge is a flat per-export

        baseline plus a per-row CPM on every row returned, at the rate that

        ``export_pricing.row_cpm_usd`` publishes. Web text bills at the standard
        Contents

        rate on POST /v1/contents; web text inlined on a search or answer
        response

        is free.


        The meaning of `cost` depends on the surface. On `/contents` responses,

        `cost` is the actual charge, and it reconciles with what that response

        billed. The exception is a `quote_only` response, where `cost` is a

        prospective price: Tako neither fetched nor billed the export, and the

        payload and url fields are null. On a search or answer downloadable

        card, `cost` is a prospective `/contents` quote (the per-export baseline

        floor) unless Tako inlined rows for the card, in which case it is what
        this

        response billed for the card. The billed cards sum to

        `usage.data.cost_usd`, never to `usage.total_cost_usd` (which always
        adds

        the flat per-request compute rate).


        On a search or answer WEB result, `cost` is always a prospective

        `/v1/contents` quote and NEVER a charge -- including when Tako inlined
        the

        page text, because inlined web text is free, so the card rule above does
        not

        carry over. That quote arrives on `cost` alone: `export_pricing` is null
        for

        web text, so zeroing `cost` on an inlined result would leave a caller no
        way

        to price a later fetch. A response whose only inlined contents were web
        text

        therefore reports `usage.data` as null -- nothing was billed for data.


        `export_pricing` carries the `/contents` export rate, so a caller can

        compute the full charge of a later export before fetching: baseline_usd
        +

        row_cpm_usd * billed_rows / 1000 + sum over classes c of

        premium_row_cpm_usd[c] * premium_rows[c] / 1000, where `billed_rows` is
        the

        SMALLER of the rows the export returns and `max_rows` clamped to

        `max_rows_ceiling`, `premium_rows` is this item's per-class record
        count, and the

        premium term applies only to an export that passes `premium=true`. One

        formula covers every format, card_json included: every export returns no

        more rows than that cap, so a card with fewer rows than the cap bills
        only

        the rows it returns. `row_cpm_usd` is the CALLER'S rate -- 0 where their
        row

        charges are waived, the same waiver a billed inline card's `cost` uses,
        and

        /contents resolves it too. `export_pricing` is null for web text

        and non-downloadable content.


        Do NOT combine `cost` with `export_pricing` on a billed inline card.
        There,

        `cost` is the amount THIS response charged, over the rows this response

        inlined, so it is not a `/contents` price for the same card: the two
        cover

        different row counts, because a search response's default inline cap is
        far

        smaller than what `/contents` returns. Read `cost` for what this
        response

        billed. Use `export_pricing` alone

        to price a `/contents` export of the same card.


        Tako populates exactly one payload group once it delivers contents:

        `data` (CSV or web text), `records` (verbose JSON), `dataset` (compact

        TakoDataset), `card_data` (rich card-type-specific JSON), or `url` plus

        `expires_at` (presigned download). `delivery` names which one, or

        `quote` when Tako delivered nothing. To get a quoted item's content,
        call

        the Contents endpoint.
    TakoCardNode:
      properties:
        id:
          type: string
          title: Id
          description: >-
            Opaque, human-friendly public id (<prefix>::<name>::<hash>, where
            prefix is ent for an entity or mt for a metric). Ids are not durable
            across knowledge-graph rebuilds — resolve them at request time
            rather than storing them.
        type:
          $ref: '#/components/schemas/GraphNodeType'
          description: Whether the node is a metric or an entity.
        name:
          type: string
          title: Name
          description: >-
            Display name. Several metrics can share a name when publishers
            report different series, such as two GDP metrics; read `description`
            to tell them apart.
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: >-
            What the node is. For a metric, what it measures, often with its
            unit and basis. For an entity, a short identification. Absent when
            Tako has none.
      type: object
      required:
        - id
        - type
        - name
      title: TakoCardNode
      description: |-
        Slim graph node for the search and answer card surface
        (TakoCard.nodes). It is deliberately narrower than GraphNode: it carries
        no `aliases` and no `subtype`. For a node's aliases, resolve the id via
        /v1/graph/node/{id}; for an entity's subtype, use /v1/graph/related.
    MetricDefinition:
      properties:
        name:
          type: string
          title: Name
          description: The metric's display name
          examples:
            - Gross Domestic Product (current US$)
        definition:
          type: string
          title: Definition
          description: Human-readable definition of the metric
      type: object
      required:
        - name
        - definition
      title: MetricDefinition
      description: |-
        Definition of a metric shown on a card. Sourced from the metric's
        ValueType definition — the same text as the in-app methodology 'Metrics'
        tab.
    DataFreshness:
      properties:
        coverage_end:
          anyOf:
            - type: string
            - type: 'null'
          title: Coverage End
          description: >-
            The last data point in the card's data, at the granularity of the
            underlying series. An annual series reports a year (2026). A monthly
            or quarterly series reports a month (2026-06). A daily or intraday
            series reports a full date (2026-06-30). This value can be in the
            future when the card includes projections. Null for card types
            without a coverage date. The value uses ISO 8601 reduced precision,
            so examine the length before you parse it. A date parser reads 2026
            as 2026-01-01, which is the start of the period and not the end. On
            a card with tabs, only the tab this response built is rendered, so
            this date describes that tab, and the same card can report a
            different date on a request that opens a different tab. Cache it
            against the response, not against the card id.
          examples:
            - '2026'
            - 2026-06
            - '2026-06-30'
        data_as_of:
          anyOf:
            - type: string
            - type: 'null'
          title: Data As Of
          description: >-
            Deprecated: use coverage_end. The same point, always as a full ISO
            date (YYYY-MM-DD). For a series whose points are periods, this date
            is the period boundary. It is not a day on which Tako observed a
            value.
          deprecated: true
          examples:
            - '2026-10-01'
        last_updated:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Updated
          description: >-
            Date Tako last refreshed the underlying data, as an ISO date
            (YYYY-MM-DD). On a card with tabs this is the ACTIVE tab's refresh
            date, for the same reason coverage_end is tab-scoped: only the tab
            this response built is rendered.
          examples:
            - '2026-07-14'
      type: object
      title: DataFreshness
      description: |-
        When the card's data ends and when Tako last refreshed it. Either field
        may be null when that date is not available for the card type.
    PlaceholderInfo:
      properties:
        withheld_source:
          type: string
          title: Withheld Source
          description: The name of the source whose data the card withholds.
        reason:
          $ref: '#/components/schemas/PlaceholderReason'
          description: >-
            Why the card withholds its data. `not_served`: the request set
            `variable_cost` to false, or the account isn't served variable-cost
            data. `over_cap`: the card's `variable_cost_max_usd` doesn't fit in
            what's left of the request's `max_variable_cost_usd`.
          default: not_served
      type: object
      required:
        - withheld_source
      title: PlaceholderInfo
      description: Why a card carries no data points.
    TakoDataset:
      properties:
        columns:
          items:
            $ref: '#/components/schemas/TakoDatasetColumn'
          type: array
          title: Columns
          description: Ordered column headers (name + type), one per position in every row.
        rows:
          items:
            items:
              anyOf:
                - type: string
                - type: number
                - type: integer
                - type: boolean
                - items:
                    additionalProperties: true
                    type: object
                  type: array
                - type: 'null'
            type: array
          type: array
          title: Rows
          description: >-
            Row data as positional cell arrays aligned to `columns` order. Cells
            are string/number/boolean/null, or an array of objects in a column
            typed 'array'; nulls are preserved, never coerced.
        total_rows:
          type: integer
          title: Total Rows
          description: >-
            True total number of rows in the underlying data, before any
            truncation.
        truncated:
          type: boolean
          title: Truncated
          description: >-
            True when `rows` was capped and total_rows exceeds the number
            returned.
        ref:
          type: string
          title: Ref
          description: Source URL the dataset was derived from (e.g. the Tako card URL).
        sources:
          items:
            $ref: '#/components/schemas/TakoDatasetSource'
          type: array
          title: Sources
          description: 'Provenance for the dataset: the sources the rows were drawn from.'
        provenance:
          type: string
          enum:
            - query
            - web_extraction
          title: Provenance
          description: 'How the rows were produced: ''query'' (Tako data) or ''web_extraction''.'
          default: query
        redacted_cells:
          anyOf:
            - additionalProperties:
                items:
                  type: integer
                type: array
              type: object
            - type: 'null'
          title: Redacted Cells
          description: >-
            Column name to the 0-based positions in `rows` whose premium value
            was withheld; those cells are null. Set on a structured-output
            dataset slot when a premium cell was withheld, and null otherwise.
            An inline /contents dataset reports this on the content item
            instead.
      type: object
      required:
        - columns
        - rows
        - total_rows
        - truncated
        - ref
        - sources
      title: TakoDataset
      description: |-
        The dataset-slot envelope: exact retrieved rows as positional arrays
        in `columns` order. The rows come directly from the data source; the LLM
        never transcribes them.
    ExportPricing:
      properties:
        baseline_usd:
          type: number
          title: Baseline Usd
          description: Flat USD charged once per card export, independent of row count.
        row_cpm_usd:
          type: number
          title: Row Cpm Usd
          description: >-
            USD charged per 1,000 rows delivered. Card-level rate; use this
            value rather than deriving one from the card's sources. It is the
            sum of the rates of the card's separately priced data feeds, or the
            standard rate once for a card with none. Credited producers and
            cited web pages never add to it. This is 0 if your account's row
            charges are waived, in which case an export costs baseline_usd
            whatever its size.
        premium_row_cpm_usd:
          additionalProperties:
            type: number
          type: object
          title: Premium Row Cpm Usd
          description: >-
            USD charged per 1,000 premium records, keyed by premium class
            ('company_record', 'person_contact'), added on top of row_cpm_usd
            when a /contents export passes premium=true. A premium record is a
            distinct company or person that the delivered rows hold a non-null
            value for in a column of that class; the item's premium_rows reports
            the count per class. Empty when the card has no premium columns. Not
            affected by a row-charge waiver.
        free_rows:
          type: integer
          title: Free Rows
          description: >-
            Deprecated and always 0. Row allowances are gone: an account that
            pays nothing per row now reports row_cpm_usd of 0 instead, which the
            cost formula already accounts for. Stop reading this field; it will
            be removed.
          default: 0
          deprecated: true
        max_rows_ceiling:
          type: integer
          title: Max Rows Ceiling
          description: >-
            Hard cap on rows a single export can return and bill; a larger
            requested max_rows is clamped to this. No format bills more than the
            clamped max_rows, and none bills more rows than it returns. Every
            format obeys this ceiling, including card_json.
        variable_cost_max_usd:
          anyOf:
            - type: number
            - type: 'null'
          title: Variable Cost Max Usd
          description: >-
            Set only for a card with data from a source priced per unit: the
            most the source's minimum charge for an export of this card can be.
            An export charges whichever is larger, its own price or that
            minimum, and the quoted cost already accounts for it. The minimum is
            known only after the export, so the actual charge can be lower. The
            export's usage.variable_cost reports a different amount: only what
            the export charged above its own price. On a search or answer card,
            it also bounds the minimum charge for serving that card with its
            data.
      type: object
      required:
        - baseline_usd
        - row_cpm_usd
        - max_rows_ceiling
      title: ExportPricing
      description: >-
        Card export pricing rate for the /contents endpoint, published so a

        caller can compute an export's cost before fetching. A /contents
        export's

        own price = baseline_usd + row_cpm_usd * rows / 1000 + sum over classes
        c of

        premium_row_cpm_usd[c] * premium_rows[c] / 1000, rows <=
        max_rows_ceiling, and

        premium_rows[c] the export's premium record count for class c.

        For a card with data from a source priced per unit, the export charges
        the

        larger of its own price and that source's minimum, and

        variable_cost_max_usd is the most that minimum can be.


        row_cpm_usd is the card-level rate and is authoritative: don't derive it

        from the card's listed sources. It is the sum of the rates of the card's

        separately priced data feeds. A card with no separately priced feed
        bills

        the standard rate once, however many sources it lists. An organization
        the

        card credits only as the producer of a redistributed number, and a web
        page

        it cites, never adds to the rate. There is no per-source breakdown. It
        is

        per caller: an account whose row charges are waived sees 0 here, and the

        same formula then yields the baseline alone, which is exactly what that

        account is billed.
    ColumnDescriptor:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: >-
            The column header as exported. This is the CSV header, the
            json_records key, and the dataset column label for this column.
        metric:
          anyOf:
            - type: string
            - type: 'null'
          title: Metric
          description: What the column measures, for example 'Median Sales Price'.
        entity:
          anyOf:
            - type: string
            - type: 'null'
          title: Entity
          description: >-
            What the column is measured for: the resolved values of every
            dimension the series is filtered to, joined with an em dash — for
            example 'Austin, TX — Condo'. A card filtered on one dimension
            reports that one value. This field reports resolved display values
            only and never an internal identifier.
        unit:
          anyOf:
            - type: string
            - type: 'null'
          title: Unit
          description: The unit of every value in the column, for example 'USD'.
        dtype:
          anyOf:
            - $ref: '#/components/schemas/TakoDatasetColumnType'
            - type: 'null'
          description: The data type of the column, inferred from the exported values.
        premium_class:
          anyOf:
            - $ref: '#/components/schemas/PremiumClass'
            - type: 'null'
          description: >-
            Set when the column is premium: 'company_record' or
            'person_contact'. Unless the export passed premium=true, a cell that
            held a value reads [premium: withheld] in CSV and is null in JSON
            formats, so a CSV reader can't parse this column as its dtype; the
            item's redacted_cells says which rows held a value. Null for every
            other column.
      type: object
      title: ColumnDescriptor
      description: |-
        Describes one exported column.

        Manifest entry `i` describes column `i`, and its `name` equals that
        column's header.
    GraphNodeType:
      type: string
      enum:
        - metric
        - entity
      title: GraphNodeType
      description: >-
        A `metric` is a measurable quantity, such as GDP; an `entity` is what
        one is measured for, such as France.
    PlaceholderReason:
      type: string
      enum:
        - not_served
        - over_cap
      title: PlaceholderReason
    TakoDatasetColumn:
      properties:
        name:
          type: string
          title: Name
          description: Column name.
        type:
          $ref: '#/components/schemas/TakoDatasetColumnType'
          description: >-
            Logical column type: 'string', 'number', 'boolean', 'date',
            'datetime', or 'array'. Temporal cells are ISO-8601 strings. An
            'array' column holds an array of objects, or null.
        unit:
          anyOf:
            - type: string
            - type: 'null'
          title: Unit
          description: >-
            Structured unit for the column values, e.g. 'USD billions', '%'.
            Null when unitless.
      type: object
      required:
        - name
        - type
      title: TakoDatasetColumn
      description: Typed header entry; `type` is the JSON-facing column type.
    TakoDatasetSource:
      properties:
        name:
          type: string
          title: Name
          description: Human-readable source name (e.g. 'FRED', 'S&P Global').
        index:
          type: string
          enum:
            - data
            - web
          title: Index
          description: 'Source index the rows came from: ''data'' (Tako) or ''web''.'
          default: data
      type: object
      required:
        - name
      title: TakoDatasetSource
      description: |-
        Per-dataset provenance entry. `index` names the source index, not a
        citation display number. It is "data" for every dataset today — web
        content never fills a dataset slot.
    TakoDatasetColumnType:
      type: string
      enum:
        - string
        - number
        - boolean
        - date
        - datetime
        - array
      title: TakoDatasetColumnType
      description: |-
        Logical column type declared in a TakoDataset header. Temporal cells
        are ISO-8601 strings. Each column declares 'date' or 'datetime' on its
        own: a temporal column whose non-null values are all timezone-naive
        midnights declares 'date'.
    PremiumClass:
      type: string
      enum:
        - person_contact
        - company_record
      title: PremiumClass
      description: >-
        The price class of a premium column. Person and company records are
        licensed at different per-record rates.
  headers:
    RateLimit-Limit:
      description: Requests allowed in the current rate-limit window.
      schema:
        type: integer
    RateLimit-Remaining:
      description: Requests left in the current rate-limit window.
      schema:
        type: integer
    RateLimit-Reset:
      description: Seconds until the current window frees capacity.
      schema:
        type: integer
    RateLimit-Policy:
      description: The rate-limit policy, e.g. 60;w=60 (60 requests per 60-second window).
      schema:
        type: string
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-Key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.