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

# What has been read for one of the team's targets, source by source, and what's missing and why

> Says what PodData has read for one of your targets, so a page can say how it was built: every source in the catalog and where it `stands` (`read`, `due`, `waiting` on a link, `off_here`, `by_request`, `not_read` or `not_built`), what each holds tied to the company over which days, how it was last read, and the known breaks in the window, with the same counted for each confirmed rival. `read` says whether the read you last asked for is `going`, `done` or `held` by a day's cap, for the target and each rival, with each reader still to run.

**Before:** The company is one of your targets (`POST /targets`), its links and rivals confirmed by a person, and a read asked for with `POST /targets/{company}/read`.

**Next:** While `read` is `going`, ask again in a few minutes. When it's `held`, come back after midnight UTC or go on with what has run; when it's `done`, go on: the target's folder (`GET /targets/{company}/folder`) and a report (`POST /diligence-reports`).

**Limits:** Your own targets only: another company is a `404`. A source held by a day's cap, or past its share of a day's requests, opens at the next midnight UTC; an ask lapses a day after it was made.

**MCP tool:** `target_coverage`, 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}/coverage
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}/coverage:
    get:
      tags:
        - Reads
      summary: >-
        What has been read for one of the team's targets, source by source, and
        what's missing and why
      description: >-
        Says what PodData has read for one of your targets, so a page can say
        how it was built: every source in the catalog and where it `stands`
        (`read`, `due`, `waiting` on a link, `off_here`, `by_request`,
        `not_read` or `not_built`), what each holds tied to the company over
        which days, how it was last read, and the known breaks in the window,
        with the same counted for each confirmed rival. `read` says whether the
        read you last asked for is `going`, `done` or `held` by a day's cap, for
        the target and each rival, with each reader still to run.


        **Before:** The company is one of your targets (`POST /targets`), its
        links and rivals confirmed by a person, and a read asked for with `POST
        /targets/{company}/read`.


        **Next:** While `read` is `going`, ask again in a few minutes. When it's
        `held`, come back after midnight UTC or go on with what has run; when
        it's `done`, go on: the target's folder (`GET
        /targets/{company}/folder`) and a report (`POST /diligence-reports`).


        **Limits:** Your own targets only: another company is a `404`. A source
        held by a day's cap, or past its share of a day's requests, opens at the
        next midnight UTC; an ask lapses a day after it was made.
      operationId: getTargetCoverage
      parameters:
        - schema:
            type: string
            maxLength: 64
          required: true
          name: company
          in: path
        - schema:
            type: string
            maxLength: 32
            description: One family of sources, such as reviews or news
          required: false
          description: One family of sources, such as reviews or news
          name: family
          in: query
        - schema:
            type: string
            format: date
            description: >-
              The window the known breaks are read over, from; three years
              before `to` if left out
          required: false
          description: >-
            The window the known breaks are read over, from; three years before
            `to` if left out
          name: from
          in: query
        - schema:
            type: string
            format: date
            description: And to; today if left out
          required: false
          description: And to; today if left out
          name: to
          in: query
      responses:
        '200':
          description: >-
            Every source in the catalog as it stands for the target, read first,
            and its confirmed rivals counted
          content:
            application/json:
              examples:
                made-up:
                  summary: 'Made up: no team’s data'
                  value:
                    company:
                      id: example-water
                      name: Example Water
                    window:
                      from: '2023-11-17'
                      to: '2026-11-17'
                    links:
                      confirmed: 3
                      proposed: 1
                      struck: 0
                    counted:
                      read: 1
                      due: 0
                      waiting: 0
                      off_here: 0
                      by_request: 0
                      not_read: 0
                      not_built: 0
                    sources:
                      - id: google-maps
                        name: Google Maps reviews and listings
                        family:
                          id: reviews
                          name: Reviews
                        route: Public page
                        cadence: Weekly
                        stands: read
                        why: null
                        needs:
                          - google_place
                        links:
                          confirmed: 2
                          proposed: 0
                        holds:
                          records: 0
                          signals: 412
                          documents: 0
                          from: '2021-03-02'
                          to: '2026-11-16'
                        last_ok: '2026-11-16T09:15:00.000Z'
                        last_run:
                          at: '2026-11-17T09:15:00.000Z'
                          status: capped
                        pull:
                          captured_at: '2026-11-16T09:15:00.000Z'
                          sort: newest
                          filter: null
                          method: apify
                          total: 430
                          items: 412
                          held: 412
                        breaks: []
                    read:
                      asked_at: '2026-11-17T09:00:00.000Z'
                      until: '2026-11-18T09:00:00.000Z'
                      state: held
                      queued: 2
                      ran: 1
                      left:
                        - id: google-maps
                          name: Google Maps reviews and listings
                          state: held
                          why: >-
                            Its run for Example Water at 2026-11-17 09:15 UTC
                            stopped at a day's cap: it reads Example Water again
                            after midnight UTC.
                          opens: '2026-11-18T00:00:00.000Z'
                      why: >-
                        The read of Example Water asked for at 2026-11-17 09:00
                        UTC is held: Google Maps reviews and listings, until
                        2026-11-18 00:00 UTC. 1 of 2 readers have run; come back
                        after midnight UTC, or go on with what has run.
                    rivals:
                      - company:
                          id: example-springs
                          name: Example Springs
                        links:
                          confirmed: 1
                          proposed: 0
                        sources:
                          - id: gdelt
                            stands: read
                            holds:
                              records: 0
                              signals: 9
                              documents: 0
                              from: '2025-02-11'
                              to: '2026-11-12'
                        read:
                          asked_at: '2026-11-17T09:00:00.000Z'
                          until: '2026-11-18T09:00:00.000Z'
                          state: done
                          queued: 1
                          ran: 1
                          left: []
                          why: >-
                            The read of Example Springs asked for at 2026-11-17
                            09:00 UTC is done: its reader has run since. Go on.
              schema:
                type: object
                properties:
                  company:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                    required:
                      - id
                      - name
                  window:
                    type: object
                    properties:
                      from:
                        type: string
                      to:
                        type: string
                    required:
                      - from
                      - to
                  links:
                    type: object
                    properties:
                      confirmed:
                        type: integer
                      proposed:
                        type: integer
                      struck:
                        type: integer
                    required:
                      - confirmed
                      - proposed
                      - struck
                  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
                  sources:
                    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
                        route:
                          type: string
                        cadence:
                          type: string
                        stands:
                          type: string
                          enum:
                            - read
                            - due
                            - waiting
                            - off_here
                            - by_request
                            - not_read
                            - not_built
                        why:
                          type:
                            - string
                            - 'null'
                        needs:
                          type:
                            - array
                            - 'null'
                          items:
                            type: string
                        links:
                          type:
                            - object
                            - 'null'
                          properties:
                            confirmed:
                              type: integer
                            proposed:
                              type: integer
                          required:
                            - confirmed
                            - proposed
                        holds:
                          type:
                            - object
                            - 'null'
                          properties:
                            records:
                              type: integer
                            signals:
                              type: integer
                            documents:
                              type: integer
                            from:
                              type:
                                - string
                                - 'null'
                            to:
                              type:
                                - string
                                - 'null'
                          required:
                            - records
                            - signals
                            - documents
                            - from
                            - to
                        last_ok:
                          type:
                            - string
                            - 'null'
                        last_run:
                          type:
                            - object
                            - 'null'
                          properties:
                            at:
                              type: string
                            status:
                              type: string
                              enum:
                                - running
                                - ok
                                - failed
                                - capped
                          required:
                            - at
                            - status
                        pull:
                          type:
                            - object
                            - 'null'
                          properties:
                            captured_at:
                              type: string
                            sort:
                              type: string
                            filter:
                              type:
                                - string
                                - 'null'
                            method:
                              type: string
                            total:
                              type:
                                - number
                                - 'null'
                            items:
                              type: integer
                            held:
                              type: integer
                          required:
                            - captured_at
                            - sort
                            - filter
                            - method
                            - total
                            - items
                            - held
                        breaks:
                          type: array
                          items:
                            type: object
                            properties:
                              sources:
                                type: array
                                items:
                                  type: string
                              from:
                                type: string
                              to:
                                type:
                                  - string
                                  - 'null'
                              approximate:
                                type: boolean
                              effect:
                                type: string
                                enum:
                                  - mark
                                  - mask
                              what:
                                type: string
                              url:
                                type: string
                            required:
                              - sources
                              - from
                              - to
                              - approximate
                              - effect
                              - what
                              - url
                      required:
                        - id
                        - name
                        - family
                        - route
                        - cadence
                        - stands
                        - why
                        - needs
                        - links
                        - holds
                        - last_ok
                        - last_run
                        - pull
                        - breaks
                  read:
                    type:
                      - object
                      - 'null'
                    properties:
                      asked_at:
                        type: string
                      until:
                        type: string
                      state:
                        type: string
                        enum:
                          - going
                          - done
                          - held
                      queued:
                        type: integer
                      ran:
                        type: integer
                      left:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            state:
                              type: string
                              enum:
                                - going
                                - held
                            why:
                              type: string
                            opens:
                              type:
                                - string
                                - 'null'
                          required:
                            - id
                            - name
                            - state
                            - why
                            - opens
                      why:
                        type: string
                    required:
                      - asked_at
                      - until
                      - state
                      - queued
                      - ran
                      - left
                      - why
                  rivals:
                    type: array
                    items:
                      type: object
                      properties:
                        company:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                          required:
                            - id
                            - name
                        links:
                          type: object
                          properties:
                            confirmed:
                              type: integer
                            proposed:
                              type: integer
                          required:
                            - confirmed
                            - proposed
                        sources:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              stands:
                                type: string
                                enum:
                                  - read
                                  - due
                                  - waiting
                                  - off_here
                                  - by_request
                                  - not_read
                                  - not_built
                              holds:
                                type: object
                                properties:
                                  records:
                                    type: integer
                                  signals:
                                    type: integer
                                  documents:
                                    type: integer
                                  from:
                                    type:
                                      - string
                                      - 'null'
                                  to:
                                    type:
                                      - string
                                      - 'null'
                                required:
                                  - records
                                  - signals
                                  - documents
                                  - from
                                  - to
                            required:
                              - id
                              - stands
                              - holds
                        read:
                          type:
                            - object
                            - 'null'
                          properties:
                            asked_at:
                              type: string
                            until:
                              type: string
                            state:
                              type: string
                              enum:
                                - going
                                - done
                                - held
                            queued:
                              type: integer
                            ran:
                              type: integer
                            left:
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: string
                                  name:
                                    type: string
                                  state:
                                    type: string
                                    enum:
                                      - going
                                      - held
                                  why:
                                    type: string
                                  opens:
                                    type:
                                      - string
                                      - 'null'
                                required:
                                  - id
                                  - name
                                  - state
                                  - why
                                  - opens
                            why:
                              type: string
                          required:
                            - asked_at
                            - until
                            - state
                            - queued
                            - ran
                            - left
                            - why
                      required:
                        - company
                        - links
                        - sources
                        - read
                required:
                  - company
                  - window
                  - links
                  - counted
                  - sources
                  - read
                  - rivals
        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/example-water/coverage' \
              -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.