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

# Everything PodData holds tied to one of the team's targets, a part a company, source by source, each with its files

> Everything PodData holds for one of your targets, as files: the index of a folder with a part for each company, the target first, then each confirmed rival and its listed parent and comparables. Each part lists, source by source, its records and signals by kind, each with its count, its first and last day, its CSV file's address and the same rows as JSON, and its documents. For the target it adds its quotes' two files, your team's own licensed figures, your reports on it, and every source that holds nothing, with why. `?format=zip` is every file at once, with a README, `coverage.csv` and this index.

**Before:** The company is one of your targets, and PodData has read it: after `POST /targets/{company}/read`, wait for `GET /targets/{company}/coverage` to show its sources read.

**Next:** Fetch each `file` (or `rows` where a file is held back) by its own address, or the whole `download`. A long file stops at its row limit and gives the cursor for the rest in `X-PodData-Next`. Your reports are read whole at `GET /diligence-reports/{id}`.

**Limits:** One call for the index and one for the zip. A file is at most 10,000 rows and the zip 100,000 in all; past that, a file is left out and the README gives its address. A review or retail source's file isn't handed on yet, so `file` is null and `held` says why: read its rows as JSON. Whole documents aren't in the zip: each is read on its own at `GET /documents/{id}`, under the key's daily limit.

**MCP tool:** `target_folder`, on PodData's MCP server at `https://api.poddata.ai/mcp`, does what this route does, with the same key. See [The MCP server](https://docs.poddata.ai/mcp.md).


## OpenAPI

````yaml /openapi.json get /targets/{company}/folder
openapi: 3.1.0
info:
  title: PodData API
  version: 1.0.0
  description: >-
    PodData is competitive intelligence from the record: what leaders said on
    podcasts, in interviews and at their own events, as quotes with the speaker,
    the source, the day and the second; and, for a diligence, what public
    sources say about a company and its rivals, read through links a person on
    your team has confirmed.


    ## Quick start


    1. **A key.** Someone on your team makes one in the workspace, Settings ›
    API keys. Send it on every call as `Authorization: Bearer pd_live_…`. Keep
    it in an environment variable, such as `PODDATA_API_KEY`, and never print it
    or write it to a file.

    2. **A target.** `POST /targets` with a company's `name` and `domain`, an id
    from `GET /companies?q=`, or its SEC `ticker`.

    3. **Its links and rivals.** `POST /targets/{company}/find` and `POST
    /targets/{company}/rivals/find` propose them, each with the page that shows
    it. Show each one to a person, and confirm it only on their yes.

    4. **A read.** `POST /targets/{company}/read` with `{"rivals": true}` asks
    PodData to read the target and its confirmed rivals now. `GET
    /targets/{company}/coverage` says what has been read, source by source.

    5. **The files.** `GET /targets/{company}/folder` lists a file for each
    source, for the target and each confirmed rival. `?format=zip` is all of
    them at once.

    6. **A report.** `POST /diligence-reports` makes one with five empty pages.
    Write each with `PUT /diligence-reports/{id}/pages/{page}`, check it with
    `POST /diligence-reports/{id}/check`, and read it with every figure filled
    with `GET /diligence-reports/{id}`. Or have PodData's own agent write it,
    `POST /diligence-reports/{id}/runs`, and follow the run with `GET
    /diligence-runs/{id}`.


    The tags below are in that order. Each operation says what has to be true
    first, what to call next and its limits, with a made-up example of the call
    and its answer.


    **For an assistant,** start from `https://api.poddata.ai/llms.txt`, which
    needs no key: the same steps, the MCP server, and PodData's diligence skill
    with its puller, which saves a target's folder, its rivals' and its reports
    to disk. The MCP server does what the API does:
    `https://api.poddata.ai/mcp`, with the same key or by signing in to PodData,
    and each operation here names its tool in `x-mcp-tool`. To add it to Claude
    Code with the key read from the environment each time it starts, never
    written down, run this as it is, in single quotes: `claude mcp add
    --transport http --scope project poddata https://api.poddata.ai/mcp --header
    'Authorization: Bearer ${PODDATA_API_KEY}'`.


    **Limits.** 120 requests a minute a key, then a `429` with `Retry-After`. A
    team's plan sets how many reads, rival finds and filers it may ask for a
    day, and a call past one is a `403` with the code `plan` that says the
    limit. A list or a file holds at most 80 words in a row of a source's own
    text; a whole document or transcript comes from its own route, one at a
    time, under a daily limit.


    **Errors** are `{"error": {"code": "…", "message": "…"}}`, the message a
    sentence that says what to do.
servers:
  - url: https://api.poddata.ai/v1
security:
  - key: []
tags:
  - name: Targets
    description: >-
      Start here. The companies your team looks at: add one by its name and
      domain, by an id from `GET /companies`, or by its SEC ticker. A target is
      your team's alone, and nothing says another team looks at it.
  - name: Links
    description: >-
      A target's own domain, listings and accounts. PodData proposes them from
      its own site, and reads only through a link a person on your team has
      confirmed.
  - name: Rivals
    description: >-
      The companies a target competes with. PodData finds and tests candidates
      and proposes only the rivals; a person confirms each, and then it is read
      beside the target.
  - name: Reads
    description: >-
      Ask PodData to read a target and its confirmed rivals now, and see what
      has been read for it, source by source, and what is missing and why.
  - name: Records and signals
    description: >-
      What PodData read about a company through its confirmed links: records,
      such as filings, licences, cases and stories, and signals, such as reviews
      and ratings, each with its own day and its page on the source's site. And
      the figures your team's own data licences read.
  - name: Ads and site
    description: >-
      A brand's ads in Meta's US ad library, from PodData's weekly reads, and
      the pages of a company's own site as PodData read them.
  - name: Number tools
    description: >-
      Figures computed on the server, so an assistant never pages through
      thousands of reviews or does the sums itself: ratings, complaints, a
      series, a timeline, ads and a site, for a company beside its confirmed
      rivals. Each answers the figures, the rows behind them, the evidence and
      how they were built.
  - name: Folder
    description: >-
      Everything PodData holds for a target and its confirmed rivals, as files:
      an index, a CSV a source and kind, and one zip.
  - name: Reports
    description: >-
      A diligence report: an overview and five pages, each figure filled by a
      number tool when the report is read, and a check that refuses what the
      evidence doesn't hold. Your own assistant writes it a page at a time, or
      PodData's agent does.
  - name: Report runs
    description: >-
      PodData's own agent writing a report or changing one: each run's status,
      its turns and what it cost.
  - name: Quotes
    description: >-
      What people said, as quotes with the speaker, the show, the day, the
      second and a page to cite.
  - name: People
    description: >-
      The people PodData quotes, their sources and timelines, and lookups of
      someone new.
  - name: Shows and episodes
    description: The shows PodData reads and their episodes, with who spoke when.
  - name: Companies
    description: >-
      What companies said and filed themselves: their documents, events,
      transcripts, slides, posts and figures, and passages of at most 80 words
      from them.
  - name: Trackers
    description: >-
      A tracker follows a topic or a person and sends each new quote it matches
      by email, Slack or webhook.
  - name: Lists
    description: >-
      A team's own lists of people and companies, to narrow a search or a
      tracker to them.
  - name: Saved
    description: >-
      What a person signed in has saved, their saved filters and their calendar
      feed. A key, which has no person, is refused most of these.
  - name: Sources
    description: >-
      The sources PodData reads, what it holds from each, and how much of the
      watch list is covered.
  - name: Webhooks
    description: Webhooks a program registers to be sent what its trackers match.
  - name: Usage
    description: The team's calls and reads, counted by day and kind.
  - name: Help
    description: >-
      PodData's guide to itself: what each part of PodData does and where in the
      workspace it's done, topic by topic.
paths:
  /targets/{company}/folder:
    get:
      tags:
        - Folder
      summary: >-
        Everything PodData holds tied to one of the team's targets, a part a
        company, source by source, each with its files
      description: >-
        Everything PodData holds for one of your targets, as files: the index of
        a folder with a part for each company, the target first, then each
        confirmed rival and its listed parent and comparables. Each part lists,
        source by source, its records and signals by kind, each with its count,
        its first and last day, its CSV file's address and the same rows as
        JSON, and its documents. For the target it adds its quotes' two files,
        your team's own licensed figures, your reports on it, and every source
        that holds nothing, with why. `?format=zip` is every file at once, with
        a README, `coverage.csv` and this index.


        **Before:** The company is one of your targets, and PodData has read it:
        after `POST /targets/{company}/read`, wait for `GET
        /targets/{company}/coverage` to show its sources read.


        **Next:** Fetch each `file` (or `rows` where a file is held back) by its
        own address, or the whole `download`. A long file stops at its row limit
        and gives the cursor for the rest in `X-PodData-Next`. Your reports are
        read whole at `GET /diligence-reports/{id}`.


        **Limits:** One call for the index and one for the zip. A file is at
        most 10,000 rows and the zip 100,000 in all; past that, a file is left
        out and the README gives its address. A review or retail source's file
        isn't handed on yet, so `file` is null and `held` says why: read its
        rows as JSON. Whole documents aren't in the zip: each is read on its own
        at `GET /documents/{id}`, under the key's daily limit.
      operationId: getTargetFolder
      parameters:
        - schema:
            type: string
            maxLength: 64
          required: true
          name: company
          in: path
        - schema:
            type: string
            enum:
              - json
              - zip
            description: >-
              zip: everything at once, the folder's files with a README, its
              coverage and this index, at most 100,000 rows. json: the index,
              the default
          required: false
          description: >-
            zip: everything at once, the folder's files with a README, its
            coverage and this index, at most 100,000 rows. json: the index, the
            default
          name: format
          in: query
      responses:
        '200':
          description: >-
            The target, its rivals and its listed parent and comparables, each
            source with its counts, days and files, and what holds nothing and
            why; or with format=zip, the files
          content:
            application/json:
              examples:
                made-up:
                  summary: 'Made up: no team’s data'
                  value:
                    company:
                      id: northwind-dental
                      name: Northwind Dental
                    asked_at: '2026-11-14T09:00:00.000Z'
                    window:
                      from: '2023-11-14'
                      to: '2026-11-14'
                    counted:
                      read: 9
                      due: 1
                      waiting: 4
                      off_here: 2
                      by_request: 3
                      not_read: 6
                      not_built: 40
                    parts:
                      - role: target
                        company:
                          id: northwind-dental
                          name: Northwind Dental
                        sources:
                          - id: google-maps
                            name: Google Maps reviews and listings
                            family:
                              id: reviews
                              name: Reviews
                            stands: read
                            why: null
                            last_ok: '2026-11-14T06:20:00.000Z'
                            records: []
                            signals:
                              - kind: review
                                count: 412
                                from: '2024-02-11'
                                to: '2026-11-09'
                                file: null
                                rows: >-
                                  /v1/companies/northwind-dental/signals?source=google-maps&kind=review
                                held: >-
                                  A review site's file isn't handed on yet: read
                                  its rows as JSON.
                            documents:
                              count: 0
                              from: null
                              to: null
                            pages: null
                          - id: nppes-npi
                            name: CMS NPPES NPI registry
                            family:
                              id: health
                              name: Health
                            stands: read
                            why: null
                            last_ok: '2026-11-14T04:02:00.000Z'
                            records:
                              - kind: organization
                                count: 3
                                from: '2025-06-18'
                                to: '2026-10-02'
                                file: >-
                                  /v1/companies/northwind-dental/records?source=nppes-npi&kind=organization&format=csv
                                rows: >-
                                  /v1/companies/northwind-dental/records?source=nppes-npi&kind=organization
                                held: null
                            signals: []
                            documents:
                              count: 0
                              from: null
                              to: null
                            pages: null
                        documents:
                          count: 0
                          file: /v1/documents?company=northwind-dental&format=csv
                          rows: /v1/documents?company=northwind-dental
                      - role: rival
                        company:
                          id: bluebird-dental
                          name: Bluebird Dental
                        sources:
                          - id: google-maps
                            name: Google Maps reviews and listings
                            family:
                              id: reviews
                              name: Reviews
                            stands: null
                            why: null
                            last_ok: '2026-11-14T06:24:00.000Z'
                            records: []
                            signals:
                              - kind: review
                                count: 268
                                from: '2024-02-11'
                                to: '2026-11-09'
                                file: null
                                rows: >-
                                  /v1/companies/bluebird-dental/signals?source=google-maps&kind=review
                                held: >-
                                  A review site's file isn't handed on yet: read
                                  its rows as JSON.
                            documents:
                              count: 0
                              from: null
                              to: null
                            pages: null
                        documents:
                          count: 0
                          file: /v1/documents?company=bluebird-dental&format=csv
                          rows: /v1/documents?company=bluebird-dental
                    quotes:
                      said:
                        file: /v1/quotes?company=northwind-dental&format=csv
                        rows: /v1/quotes?company=northwind-dental
                      named:
                        file: /v1/quotes?named=northwind-dental&format=csv
                        rows: /v1/quotes?named=northwind-dental
                    licensed: []
                    reports:
                      - id: dlr_01JD9K4M5N6P00000000000000
                        title: 'Northwind Dental: first look'
                        status: draft
                        updated_at: '2026-11-14T08:30:00.000Z'
                        rows: /v1/diligence-reports/dlr_01JD9K4M5N6P00000000000000
                        file: >-
                          /v1/diligence-reports/dlr_01JD9K4M5N6P00000000000000?format=zip
                    not_held:
                      - id: yelp
                        name: Yelp
                        family:
                          id: reviews
                          name: Reviews
                        stands: waiting
                        why: >-
                          It reads against a confirmed yelp_business, and
                          Northwind Dental has none confirmed.
                    download: /v1/targets/northwind-dental/folder?format=zip
              schema:
                type: object
                properties:
                  company:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                    required:
                      - id
                      - name
                  asked_at:
                    type: string
                  window:
                    type: object
                    properties:
                      from:
                        type: string
                      to:
                        type: string
                    required:
                      - from
                      - to
                  counted:
                    type: object
                    properties:
                      read:
                        type: integer
                      due:
                        type: integer
                      waiting:
                        type: integer
                      off_here:
                        type: integer
                      by_request:
                        type: integer
                      not_read:
                        type: integer
                      not_built:
                        type: integer
                    required:
                      - read
                      - due
                      - waiting
                      - off_here
                      - by_request
                      - not_read
                      - not_built
                  parts:
                    type: array
                    items:
                      type: object
                      properties:
                        role:
                          type: string
                          enum:
                            - target
                            - rival
                            - parent
                            - comparable
                        company:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                          required:
                            - id
                            - name
                        sources:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                              family:
                                anyOf:
                                  - type: object
                                    properties:
                                      id:
                                        type: string
                                      name:
                                        type: string
                                    required:
                                      - id
                                      - name
                                  - type: 'null'
                              stands:
                                type:
                                  - string
                                  - 'null'
                                enum:
                                  - read
                                  - due
                                  - waiting
                                  - off_here
                                  - by_request
                                  - not_read
                                  - not_built
                                  - null
                              why:
                                type:
                                  - string
                                  - 'null'
                              last_ok:
                                type:
                                  - string
                                  - 'null'
                              records:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    kind:
                                      type: string
                                    count:
                                      type: integer
                                    from:
                                      type:
                                        - string
                                        - 'null'
                                    to:
                                      type:
                                        - string
                                        - 'null'
                                    file:
                                      type:
                                        - string
                                        - 'null'
                                    rows:
                                      type: string
                                    held:
                                      type:
                                        - string
                                        - 'null'
                                  required:
                                    - kind
                                    - count
                                    - from
                                    - to
                                    - file
                                    - rows
                                    - held
                              signals:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    kind:
                                      type: string
                                    count:
                                      type: integer
                                    from:
                                      type:
                                        - string
                                        - 'null'
                                    to:
                                      type:
                                        - string
                                        - 'null'
                                    file:
                                      type:
                                        - string
                                        - 'null'
                                    rows:
                                      type: string
                                    held:
                                      type:
                                        - string
                                        - 'null'
                                  required:
                                    - kind
                                    - count
                                    - from
                                    - to
                                    - file
                                    - rows
                                    - held
                              documents:
                                type: object
                                properties:
                                  count:
                                    type: integer
                                  from:
                                    type:
                                      - string
                                      - 'null'
                                  to:
                                    type:
                                      - string
                                      - 'null'
                                required:
                                  - count
                                  - from
                                  - to
                              pages:
                                type:
                                  - object
                                  - 'null'
                                properties:
                                  count:
                                    type: integer
                                  from:
                                    type:
                                      - string
                                      - 'null'
                                  to:
                                    type:
                                      - string
                                      - 'null'
                                  file:
                                    type: string
                                  rows:
                                    type: string
                                  why:
                                    type:
                                      - string
                                      - 'null'
                                required:
                                  - count
                                  - from
                                  - to
                                  - file
                                  - rows
                                  - why
                            required:
                              - id
                              - name
                              - family
                              - stands
                              - why
                              - last_ok
                              - records
                              - signals
                              - documents
                              - pages
                        documents:
                          type: object
                          properties:
                            count:
                              type: integer
                            file:
                              type: string
                            rows:
                              type: string
                          required:
                            - count
                            - file
                            - rows
                      required:
                        - role
                        - company
                        - sources
                        - documents
                  quotes:
                    type: object
                    properties:
                      said:
                        type: object
                        properties:
                          file:
                            type: string
                          rows:
                            type: string
                        required:
                          - file
                          - rows
                      named:
                        type: object
                        properties:
                          file:
                            type: string
                          rows:
                            type: string
                        required:
                          - file
                          - rows
                    required:
                      - said
                      - named
                  licensed:
                    type: array
                    items:
                      type: object
                      properties:
                        source:
                          type: string
                        name:
                          type: string
                        count:
                          type: integer
                        from:
                          type:
                            - string
                            - 'null'
                        to:
                          type:
                            - string
                            - 'null'
                        rows:
                          type: string
                      required:
                        - source
                        - name
                        - count
                        - from
                        - to
                        - rows
                  reports:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        title:
                          type: string
                        status:
                          type: string
                        updated_at:
                          type: string
                        rows:
                          type: string
                        file:
                          type: string
                      required:
                        - id
                        - title
                        - status
                        - updated_at
                        - rows
                        - file
                  not_held:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        family:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                          required:
                            - id
                            - name
                        stands:
                          type: string
                          enum:
                            - read
                            - due
                            - waiting
                            - off_here
                            - by_request
                            - not_read
                            - not_built
                        why:
                          type:
                            - string
                            - 'null'
                      required:
                        - id
                        - name
                        - family
                        - stands
                        - why
                  download:
                    type: string
                required:
                  - company
                  - asked_at
                  - window
                  - counted
                  - parts
                  - quotes
                  - licensed
                  - reports
                  - not_held
                  - download
            application/zip:
              schema:
                type: string
                format: binary
                description: >-
                  With format=zip: the folder's files, each as its own address
                  answers it
        default:
          description: An error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      x-codeSamples:
        - lang: bash
          label: curl, made-up values
          source: |-
            curl 'https://api.poddata.ai/v1/targets/northwind-dental/folder' \
              -H "Authorization: Bearer $PODDATA_API_KEY"
components:
  schemas:
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - bad_request
                - no_key
                - plan
                - forbidden
                - not_found
                - conflict
                - unclear
                - slow_down
                - internal
            message:
              type: string
          required:
            - code
            - message
      required:
        - error
  securitySchemes:
    key:
      type: http
      scheme: bearer
      description: >-
        An API key, sent as `Authorization: Bearer pd_live_…`. Someone on your
        team makes one in the workspace, Settings › API keys; it's shown once.
        Staging's keys start with `pd_test_`.

````

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