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

# Starts PodData's agent on a report: a first draft, or with a message, a change that leaves the rest

> Has PodData's own agent write one of your reports, in the background over some minutes: an agent for each page still `empty`, then one for the overview, each reading PodData's records through the tools an assistant has, then the report's check. On a new report that's every page; after a run that ended `capped`, the pages it left. A page that's written or waits on a source is left as it is, and with nothing left the run only checks the report. With `message`, one agent makes that change and leaves the rest. `202` with the run, `started_by` naming your key.

**Before:** The report, from `POST /diligence-reports`, on one of your targets whose links and rivals a person has confirmed and PodData has read: `GET /targets/{company}/coverage` says when the read is done.

**Next:** Read the run with `GET /diligence-runs/{id}` every minute or so until its status is `done`, `stopped`, `capped`, `refused` or `failed`, then the report with `GET /diligence-reports/{id}`. One that ended `capped` says which pages are still empty: start another run with no message to write them.

**Limits:** PodData pays for its turns, up to the run's `cap_usd`, $5, so ask the person first. One run of a report at a time: a second while one is going is a `409` naming it. No run starts while the target has a gap open, for it or a confirmed rival: no read asked, a read going or held by a day's cap, a link or rival decided after its read, or one still proposed. That's a `409` naming each gap and what fills it, with `Retry-After` when a cap holds the read. Runs a key or an assistant starts a UTC day: 0 on Free, 3 on Pro and Pilot, and 10 on Enterprise; past them a `429` with `Retry-After` at midnight UTC, and on a plan that starts none a `403`. A run started in the workspace isn't counted.

**MCP tool:** `start_report_run`, 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 post /diligence-reports/{id}/runs
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:
  /diligence-reports/{id}/runs:
    post:
      tags:
        - Report runs
      summary: >-
        Starts PodData's agent on a report: a first draft, or with a message, a
        change that leaves the rest
      description: >-
        Has PodData's own agent write one of your reports, in the background
        over some minutes: an agent for each page still `empty`, then one for
        the overview, each reading PodData's records through the tools an
        assistant has, then the report's check. On a new report that's every
        page; after a run that ended `capped`, the pages it left. A page that's
        written or waits on a source is left as it is, and with nothing left the
        run only checks the report. With `message`, one agent makes that change
        and leaves the rest. `202` with the run, `started_by` naming your key.


        **Before:** The report, from `POST /diligence-reports`, on one of your
        targets whose links and rivals a person has confirmed and PodData has
        read: `GET /targets/{company}/coverage` says when the read is done.


        **Next:** Read the run with `GET /diligence-runs/{id}` every minute or
        so until its status is `done`, `stopped`, `capped`, `refused` or
        `failed`, then the report with `GET /diligence-reports/{id}`. One that
        ended `capped` says which pages are still empty: start another run with
        no message to write them.


        **Limits:** PodData pays for its turns, up to the run's `cap_usd`, $5,
        so ask the person first. One run of a report at a time: a second while
        one is going is a `409` naming it. No run starts while the target has a
        gap open, for it or a confirmed rival: no read asked, a read going or
        held by a day's cap, a link or rival decided after its read, or one
        still proposed. That's a `409` naming each gap and what fills it, with
        `Retry-After` when a cap holds the read. Runs a key or an assistant
        starts a UTC day: 0 on Free, 3 on Pro and Pilot, and 10 on Enterprise;
        past them a `429` with `Retry-After` at midnight UTC, and on a plan that
        starts none a `403`. A run started in the workspace isn't counted.
      operationId: startDiligenceRun
      parameters:
        - schema:
            type: string
            maxLength: 64
            description: The report's id, dlr_…
          required: true
          description: The report's id, dlr_…
          name: id
          in: path
      requestBody:
        required: true
        content:
          application/json:
            examples:
              made-up:
                summary: 'Made up: no team’s data'
                value: {}
            schema:
              type: object
              properties:
                message:
                  type: string
                  minLength: 1
                  maxLength: 2000
                  description: >-
                    What to change, in a sentence or two. Left out, the run
                    writes a first draft
              additionalProperties: false
      responses:
        '202':
          description: >-
            Started: it runs in the background. Read it with GET
            /v1/diligence-runs/{id}
          content:
            application/json:
              examples:
                made-up:
                  summary: 'Made up: no team’s data'
                  value:
                    id: drn_01JD9M7Q8R9S00000000000000
                    report: dlr_01JD9K4M5N6P00000000000000
                    company: northwind-dental
                    kind: write
                    message: null
                    status: queued
                    why: null
                    model: claude-sonnet-5-5
                    playbook: '2'
                    usd: 0
                    cap_usd: 5
                    turns: 0
                    agents: []
                    refusals: null
                    started_by:
                      via: key
                      key: key_01JD9H6J7K8M00000000000000
                    created_at: '2026-11-14T10:00:00.000Z'
                    updated_at: '2026-11-14T10:00:00.000Z'
                    ended_at: null
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: drn_…
                  report:
                    type: string
                  company:
                    type: string
                  kind:
                    type: string
                    enum:
                      - write
                      - change
                  message:
                    type:
                      - string
                      - 'null'
                    description: What a person asked for, on a change
                  status:
                    type: string
                    enum:
                      - queued
                      - running
                      - waiting
                      - checking
                      - done
                      - stopped
                      - capped
                      - refused
                      - failed
                  why:
                    type:
                      - string
                      - 'null'
                    description: Why it waits or ended, in a sentence
                  model:
                    type: string
                  playbook:
                    type: string
                    description: The playbook's version
                  usd:
                    type: number
                    description: What its turns have cost so far, in dollars
                  cap_usd:
                    type: number
                    description: 'What it may spend, in dollars: the cap on a run'
                  turns:
                    type: integer
                  agents:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: >-
                            customer, competitive, news, trends, expert,
                            overview, change, check-1, check-2
                        status:
                          type: string
                          enum:
                            - running
                            - waiting
                            - done
                            - capped
                            - refused
                            - cut_off
                            - stopped
                        why:
                          type:
                            - string
                            - 'null'
                        turns:
                          type: integer
                        usd:
                          type: number
                        trace:
                          type: array
                          items:
                            type: object
                            properties:
                              turn:
                                type: integer
                              at:
                                type: string
                              model:
                                type: string
                              usd:
                                type: number
                              stop:
                                type: string
                                description: >-
                                  tool_use, end_turn, max_tokens, refusal,
                                  unreadable, …
                              tokens:
                                type: object
                                properties:
                                  input:
                                    type: integer
                                  cache_write:
                                    type: integer
                                  cache_read:
                                    type: integer
                                  output:
                                    type: integer
                                required:
                                  - input
                                  - cache_write
                                  - cache_read
                                  - output
                              tools:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    name:
                                      type: string
                                    ok:
                                      type: boolean
                                    chars:
                                      type: integer
                                  required:
                                    - name
                                    - ok
                                    - chars
                            required:
                              - turn
                              - at
                              - model
                              - usd
                              - stop
                              - tokens
                              - tools
                      required:
                        - name
                        - status
                        - why
                        - turns
                        - usd
                  refusals:
                    type:
                      - array
                      - 'null'
                    items:
                      type: string
                    description: What the check last refused, each in a sentence
                  started_by:
                    type: object
                    properties:
                      via:
                        type: string
                        enum:
                          - workspace
                          - key
                          - assistant
                        description: >-
                          Where it was started: the workspace, an API key, or an
                          assistant signed in as a person
                      key:
                        type:
                          - string
                          - 'null'
                        description: >-
                          The key's id, key_…, for a run a key started; null
                          otherwise
                    required:
                      - via
                      - key
                    description: >-
                      Who started it. A key or an assistant counts toward the
                      plan's runs a day; the workspace doesn't
                  created_at:
                    type: string
                  updated_at:
                    type: string
                  ended_at:
                    type:
                      - string
                      - 'null'
                required:
                  - id
                  - report
                  - company
                  - kind
                  - message
                  - status
                  - why
                  - model
                  - playbook
                  - usd
                  - cap_usd
                  - turns
                  - agents
                  - refusals
                  - started_by
                  - created_at
                  - updated_at
                  - ended_at
        default:
          description: An error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      x-codeSamples:
        - lang: bash
          label: curl, made-up values
          source: >-
            curl -X POST
            'https://api.poddata.ai/v1/diligence-reports/dlr_01JD9K4M5N6P00000000000000/runs'
            \
              -H "Authorization: Bearer $PODDATA_API_KEY" \
              -H 'Content-Type: application/json' \
              -d '{}'
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.