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

# The ads running at each of a brand's weekly pulls, with what started and stopped since the one before, for the target and each confirmed rival

> The ads running at each of a brand's weekly pulls, twelve weeks to `to` if left out, with what started and stopped since the pull before, for the company and each confirmed rival. A row is a company's pull. With `format=csv` its rows are a file under its columns, a number a cell, and with `format=csv&part=figures` its named figures are, a row each: counts and shares, never a review's words. Its MCP tool answers the JSON only, since no tool hands over a file.

**Before:** The company is one of your team's targets, or any company `/companies/{id}` takes. A review or record counts only where a link a person confirmed ties it (`POST /companies/{id}/links/{link}/confirm`), and a rival only once a person confirms it (`POST /companies/{id}/rivals/{rival}/confirm`). Ask for a read with `POST /targets/{company}/read` if coverage says a source hasn't been read.

**Next:** Put it in a report as an exhibit, `{"numbers": "ads_weeks", "company": "…", "params": {…}}` with these arguments as its params, through `PUT /diligence-reports/{id}/pages/{page}`, and cite a figure in the page's copy as `{exhibit-id.figure_name}`: the report fills it each time it's read. Or save the rows with `format=csv`.

**Limits:** One `api` call, as JSON or as a file. At most 200 of the ids behind the figures are listed in `evidence`, and `evidence.more` says how many aren't. Under 30 reviews a figure is `small` and comes with how many it rests on. `part` without `format=csv` is a `400`.

**MCP tool:** `numbers_ads_weeks`, 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 /companies/{id}/numbers/ads-weeks
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:
  /companies/{id}/numbers/ads-weeks:
    get:
      tags:
        - Number tools
      summary: >-
        The ads running at each of a brand's weekly pulls, with what started and
        stopped since the one before, for the target and each confirmed rival
      description: >-
        The ads running at each of a brand's weekly pulls, twelve weeks to `to`
        if left out, with what started and stopped since the pull before, for
        the company and each confirmed rival. A row is a company's pull. With
        `format=csv` its rows are a file under its columns, a number a cell, and
        with `format=csv&part=figures` its named figures are, a row each: counts
        and shares, never a review's words. Its MCP tool answers the JSON only,
        since no tool hands over a file.


        **Before:** The company is one of your team's targets, or any company
        `/companies/{id}` takes. A review or record counts only where a link a
        person confirmed ties it (`POST /companies/{id}/links/{link}/confirm`),
        and a rival only once a person confirms it (`POST
        /companies/{id}/rivals/{rival}/confirm`). Ask for a read with `POST
        /targets/{company}/read` if coverage says a source hasn't been read.


        **Next:** Put it in a report as an exhibit, `{"numbers": "ads_weeks",
        "company": "…", "params": {…}}` with these arguments as its params,
        through `PUT /diligence-reports/{id}/pages/{page}`, and cite a figure in
        the page's copy as `{exhibit-id.figure_name}`: the report fills it each
        time it's read. Or save the rows with `format=csv`.


        **Limits:** One `api` call, as JSON or as a file. At most 200 of the ids
        behind the figures are listed in `evidence`, and `evidence.more` says
        how many aren't. Under 30 reviews a figure is `small` and comes with how
        many it rests on. `part` without `format=csv` is a `400`.
      operationId: numbersAdsWeeks
      parameters:
        - schema:
            type: string
            maxLength: 64
          required: true
          name: id
          in: path
        - schema:
            type: string
            minLength: 1
            maxLength: 64
            description: 'The ad library, by catalog id: meta-ad-library if left out'
          required: false
          description: 'The ad library, by catalog id: meta-ad-library if left out'
          name: source
          in: query
        - schema:
            type: string
            format: date
            description: 'The last day: today if left out'
          required: false
          description: 'The last day: today if left out'
          name: to
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 104
            description: 'How many weeks of pulls, ending on `to`: 12 if left out'
          required: false
          description: 'How many weeks of pulls, ending on `to`: 12 if left out'
          name: weeks
          in: query
        - schema:
            type: string
            enum:
              - json
              - csv
            description: >-
              csv: the answer as a file, its rows under its columns, or with
              part=figures its named figures. json: the answer, the default
            example: csv
          required: false
          description: >-
            csv: the answer as a file, its rows under its columns, or with
            part=figures its named figures. json: the answer, the default
          name: format
          in: query
        - schema:
            type: string
            enum:
              - rows
              - figures
            description: >-
              With format=csv: rows (the default), the table behind the chart, a
              row each with a column for each of its columns; or figures, a row
              each with its label, value, unit, company, n and interval
            example: figures
          required: false
          description: >-
            With format=csv: rows (the default), the table behind the chart, a
            row each with a column for each of its columns; or figures, a row
            each with its label, value, unit, company, n and interval
          name: part
          in: query
      responses:
        '200':
          description: A row a company's pull
          content:
            application/json:
              examples:
                made-up:
                  summary: 'Made up: no team’s data'
                  value:
                    numbers: ads_weeks
                    company:
                      id: northwind-dental
                      name: Northwind Dental
                    params:
                      source: meta-ad-library
                      to: '2026-11-16'
                      weeks: 4
                    figures:
                      - name: running_latest
                        label: Ads running at the latest pull
                        value: 6
                        unit: count
                        company: northwind-dental
                        'n': 6
                        small: false
                        interval: null
                    columns:
                      - name: running
                        label: Running
                        unit: count
                    rows:
                      - key: northwind-dental:2026-11-09
                        label: Nov 9, 2026
                        kind: period
                        company: northwind-dental
                        values:
                          running: 5
                        small: false
                        day: '2026-11-09'
                        source: null
                        category: null
                        url: null
                        was: null
                      - key: northwind-dental:2026-11-16
                        label: Nov 16, 2026
                        kind: period
                        company: northwind-dental
                        values:
                          running: 6
                        small: false
                        day: '2026-11-16'
                        source: null
                        category: null
                        url: null
                        was: null
                    evidence:
                      items:
                        - kind: signal
                          id: sig_01EXAMPLE00000000000000001
                          source: meta-ad-library
                          company: northwind-dental
                          link: cln_01EXAMPLE00000000000000001
                          day: '2026-10-02'
                          url: https://maps.example/reviews/1
                          row: northwind-dental:2026-11-09
                          rating: null
                          text: null
                      total: 412
                      more: 411
                    basis:
                      sources:
                        - id: meta-ad-library
                          name: Meta's US ad library
                          network: meta
                      independent: 1
                      window:
                        from: '2025-11-17'
                        to: '2026-11-16'
                      compare: null
                      method: Made up for this example.
                      sample:
                        read: 412
                        of: 1180
                        from: '2023-02-01'
                        to: '2026-11-16'
                        days: 1385
                        undated: 0
                      breaks: []
                      periods: null
                      left_out: []
                      caveats: []
                    computed_at: '2026-11-17T14:00:00.000Z'
              schema:
                type: object
                properties:
                  numbers:
                    type: string
                    enum:
                      - rating
                      - rating_by_link
                      - rating_rivals
                      - rating_windows
                      - complaints
                      - series
                      - timeline
                      - ads
                      - ads_weeks
                      - site
                      - site_changes
                  company:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                    required:
                      - id
                      - name
                  params:
                    type: object
                    additionalProperties: {}
                  figures:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          maxLength: 60
                          pattern: ^[a-z][a-z0-9_]*$
                        label:
                          type: string
                        value:
                          type:
                            - number
                            - 'null'
                        unit:
                          type: string
                          enum:
                            - count
                            - stars
                            - share
                            - usd
                            - days
                            - number
                        company:
                          type:
                            - string
                            - 'null'
                        'n':
                          type:
                            - integer
                            - 'null'
                        small:
                          type: boolean
                        interval:
                          type:
                            - object
                            - 'null'
                          properties:
                            low:
                              type: number
                            high:
                              type: number
                          required:
                            - low
                            - high
                      required:
                        - name
                        - label
                        - value
                        - unit
                        - company
                        - 'n'
                        - small
                        - interval
                  columns:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          maxLength: 60
                          pattern: ^[a-z][a-z0-9_]*$
                        label:
                          type: string
                        unit:
                          type: string
                          enum:
                            - count
                            - stars
                            - share
                            - usd
                            - days
                            - number
                      required:
                        - name
                        - label
                        - unit
                  rows:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        label:
                          type: string
                        kind:
                          type: string
                          enum:
                            - company
                            - link
                            - star
                            - period
                            - topic
                            - event
                        company:
                          type:
                            - string
                            - 'null'
                        values:
                          type: object
                          additionalProperties:
                            type:
                              - number
                              - 'null'
                        small:
                          type: boolean
                        day:
                          type:
                            - string
                            - 'null'
                        source:
                          type:
                            - string
                            - 'null'
                        category:
                          type:
                            - string
                            - 'null'
                        url:
                          type:
                            - string
                            - 'null'
                        was:
                          type:
                            - array
                            - 'null'
                          items:
                            type: object
                            properties:
                              label:
                                type: string
                              values:
                                type: object
                                additionalProperties:
                                  type:
                                    - number
                                    - 'null'
                              day:
                                type:
                                  - string
                                  - 'null'
                              seen_from:
                                type: string
                              seen_to:
                                type: string
                            required:
                              - label
                              - values
                              - day
                              - seen_from
                              - seen_to
                      required:
                        - key
                        - label
                        - kind
                        - company
                        - values
                        - small
                        - day
                        - source
                        - category
                        - url
                        - was
                  evidence:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            kind:
                              type: string
                              enum:
                                - signal
                                - record
                                - document
                                - quote
                                - snapshot
                            id:
                              type: string
                            source:
                              type: string
                            company:
                              type:
                                - string
                                - 'null'
                            link:
                              type:
                                - string
                                - 'null'
                            day:
                              type:
                                - string
                                - 'null'
                            url:
                              type:
                                - string
                                - 'null'
                            row:
                              type:
                                - string
                                - 'null'
                            rating:
                              type:
                                - number
                                - 'null'
                            text:
                              type:
                                - string
                                - 'null'
                          required:
                            - kind
                            - id
                            - source
                            - company
                            - link
                            - day
                            - url
                            - row
                            - rating
                            - text
                        maxItems: 200
                      total:
                        type: integer
                      more:
                        type: integer
                    required:
                      - items
                      - total
                      - more
                  basis:
                    type: object
                    properties:
                      sources:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            network:
                              type: string
                          required:
                            - id
                            - name
                            - network
                      independent:
                        type: integer
                      window:
                        type:
                          - object
                          - 'null'
                        properties:
                          from:
                            type: string
                          to:
                            type: string
                        required:
                          - from
                          - to
                      compare:
                        type:
                          - object
                          - 'null'
                        properties:
                          from:
                            type: string
                          to:
                            type: string
                        required:
                          - from
                          - to
                      method:
                        type: string
                      sample:
                        type: object
                        properties:
                          read:
                            type: integer
                          of:
                            type:
                              - integer
                              - 'null'
                          from:
                            type:
                              - string
                              - 'null'
                          to:
                            type:
                              - string
                              - 'null'
                          days:
                            type: integer
                          undated:
                            type: integer
                        required:
                          - read
                          - of
                          - from
                          - to
                          - days
                          - undated
                      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
                      periods:
                        type:
                          - object
                          - 'null'
                        properties:
                          has:
                            type: array
                            items:
                              type: string
                          lacks:
                            type: array
                            items:
                              type: string
                        required:
                          - has
                          - lacks
                      left_out:
                        type: array
                        items:
                          type: object
                          properties:
                            what:
                              type: string
                            count:
                              type: integer
                            why:
                              type: string
                          required:
                            - what
                            - count
                            - why
                      caveats:
                        type: array
                        items:
                          type: string
                    required:
                      - sources
                      - independent
                      - window
                      - compare
                      - method
                      - sample
                      - breaks
                      - periods
                      - left_out
                      - caveats
                  computed_at:
                    type: string
                required:
                  - numbers
                  - company
                  - params
                  - figures
                  - columns
                  - rows
                  - evidence
                  - basis
                  - computed_at
            text/csv:
              example: "\"name\",\"label\",\"value\",\"unit\",\"company\",\"n\",\"small\",\"interval_low\",\"interval_high\"\r\n\"average\",\"Average rating, made up for this example\",\"4.1\",\"stars\",\"northwind-dental\",\"412\",\"no\",\"3.9\",\"4.3\"\r\n"
              schema:
                type: string
                description: >-
                  With format=csv: the answer's rows under its columns, or with
                  part=figures its figures, as a file
        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/companies/northwind-dental/numbers/ads-weeks?source=meta-ad-library&weeks=4'
            \
              -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.