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

# Finds one of the team's targets' rivals: candidates tested like for like from their own sites, only the rivals proposed

> Finds one of your targets' rivals. PodData gathers candidates from your `list`, from the records it holds (a licensing board's other licensees, the same specialty in the same towns), from stories and deals that name the target, and from the open web where that's on here; `sources` says where it looked. It reads each candidate's own site and has two models of different families say, blind to each other, what it sells, to whom and where, and so what it is to the target. Only a rival both agree on is proposed, never confirmed; every other candidate comes back in `left_out` with its verdict and why (a supplier, a different buyer, a different product, another business of the same name, or unclear). `overlap` says what the two firms share that no model said: industry codes, towns and words, and `supported: false` marks a rival only the models' reading backs.

**Before:** The company is one of your targets. Give `about`, what it sells, to whom and where, if its own site can't be read: a site whose terms bar reading it is a `400` that asks for it.

**Next:** Show each proposed rival, its page and why to a person, and confirm the right ones with `POST /companies/{id}/rivals/{rival}/confirm`.

**Limits:** At most 15 candidates tested an ask, your list first; the rest come back in `not_tested`. As many asks a UTC day as the plan's rival finds, 1 on Free, 3 on Pro and Pilot, and no limit on Enterprise; past it, a `403` with the code `plan`. `cost` says what the ask spent. A rival confirmed or struck already isn't tested again.

**MCP tool:** `find_rivals`, 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 /targets/{company}/rivals/find
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}/rivals/find:
    post:
      tags:
        - Rivals
      summary: >-
        Finds one of the team's targets' rivals: candidates tested like for like
        from their own sites, only the rivals proposed
      description: >-
        Finds one of your targets' rivals. PodData gathers candidates from your
        `list`, from the records it holds (a licensing board's other licensees,
        the same specialty in the same towns), from stories and deals that name
        the target, and from the open web where that's on here; `sources` says
        where it looked. It reads each candidate's own site and has two models
        of different families say, blind to each other, what it sells, to whom
        and where, and so what it is to the target. Only a rival both agree on
        is proposed, never confirmed; every other candidate comes back in
        `left_out` with its verdict and why (a supplier, a different buyer, a
        different product, another business of the same name, or unclear).
        `overlap` says what the two firms share that no model said: industry
        codes, towns and words, and `supported: false` marks a rival only the
        models' reading backs.


        **Before:** The company is one of your targets. Give `about`, what it
        sells, to whom and where, if its own site can't be read: a site whose
        terms bar reading it is a `400` that asks for it.


        **Next:** Show each proposed rival, its page and why to a person, and
        confirm the right ones with `POST
        /companies/{id}/rivals/{rival}/confirm`.


        **Limits:** At most 15 candidates tested an ask, your list first; the
        rest come back in `not_tested`. As many asks a UTC day as the plan's
        rival finds, 1 on Free, 3 on Pro and Pilot, and no limit on Enterprise;
        past it, a `403` with the code `plan`. `cost` says what the ask spent. A
        rival confirmed or struck already isn't tested again.
      operationId: findTargetRivals
      parameters:
        - schema:
            type: string
            maxLength: 64
          required: true
          name: company
          in: path
      requestBody:
        required: false
        content:
          application/json:
            examples:
              made-up:
                summary: 'Made up: no team’s data'
                value:
                  list:
                    - name: Bluebird Dental
                      domain: bluebird-dental.example
                    - name: Summit Dental Supply
                      domain: summit-dental-supply.example
                  from:
                    - list
            schema:
              type: object
              properties:
                list:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        minLength: 2
                        maxLength: 120
                      domain:
                        type: string
                        minLength: 3
                        maxLength: 253
                    required:
                      - name
                    additionalProperties: false
                  maxItems: 40
                  description: >-
                    Candidates the caller gives, each a name and, where known,
                    its own domain. At most 15 are tested an ask
                about:
                  type: string
                  minLength: 10
                  maxLength: 500
                  description: >-
                    What the target sells, to whom and where, in a sentence:
                    read from its own site when left out
                from:
                  type: array
                  items:
                    type: string
                    enum:
                      - list
                      - records
                      - news
                      - web
                  minItems: 1
                  description: >-
                    Where to look: list, records, news and web. All of them if
                    left out
              additionalProperties: false
      responses:
        '200':
          description: >-
            What it found: the rivals proposed, never confirmed, and every other
            candidate left out with why
          content:
            application/json:
              examples:
                made-up:
                  summary: 'Made up: no team’s data'
                  value:
                    company:
                      id: northwind-dental
                      name: Northwind Dental
                    target:
                      about: >-
                        General and cosmetic dentistry for families, at three
                        clinics in Riverside County, California
                      from: site
                      page: https://northwind-dental.example/
                    proposed:
                      - name: Bluebird Dental
                        domain: bluebird-dental.example
                        found:
                          from: list
                          source: null
                          why: On your list
                          url: null
                        verdict: rival
                        sells: General and cosmetic dentistry
                        to: Families and adults
                        where: Riverside and Corona, California
                        shows:
                          words: >-
                            Family dentistry in Riverside and Corona, with
                            same-day crowns and cleanings for all ages.
                          page: https://bluebird-dental.example/
                        reads:
                          - model: first model
                            verdict: rival
                            why: >-
                              The same care for the same patients in the same
                              towns.
                          - model: second model
                            verdict: rival
                            why: General dentistry in two of the target’s towns.
                        overlap:
                          codes:
                            - NPI specialty 1223G0001X
                          towns:
                            - Riverside
                          terms:
                            - crowns
                            - cleanings
                            - family
                          supported: true
                        why: >-
                          Both reads say it sells general dentistry to families
                          in Riverside.
                        rival:
                          id: bluebird-dental
                          name: Bluebird Dental
                        state: proposed
                        added: true
                    left_out:
                      - name: Summit Dental Supply
                        domain: summit-dental-supply.example
                        found:
                          from: list
                          source: null
                          why: On your list
                          url: null
                        verdict: supplier
                        sells: Instruments and consumables for dental practices
                        to: Dental practices
                        where: The United States
                        shows:
                          words: >-
                            Everything your practice needs, from impression
                            trays to autoclaves, shipped next day.
                          page: https://summit-dental-supply.example/
                        reads:
                          - model: first model
                            verdict: supplier
                            why: It sells to practices like the target.
                          - model: second model
                            verdict: supplier
                            why: A distributor to dental offices.
                        overlap:
                          codes: []
                          towns: []
                          terms: []
                          supported: false
                        why: It supplies dental practices, so it isn’t a rival.
                    decided: []
                    not_tested: []
                    sources:
                      - from: list
                        looked: true
                        found: 2
                        why: null
                      - from: records
                        looked: false
                        found: 0
                        why: Not asked for
                      - from: news
                        looked: false
                        found: 0
                        why: Not asked for
                      - from: web
                        looked: false
                        found: 0
                        why: Not asked for
                    cost:
                      usd: 0.03
                      model_calls: 4
                      searches: 0
                      pages: 7
                    asked_today: 1
                    limit: 3
              schema:
                type: object
                properties:
                  company:
                    type: object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                    required:
                      - id
                      - name
                  target:
                    type: object
                    properties:
                      about:
                        type: string
                      from:
                        type: string
                        enum:
                          - caller
                          - site
                      page:
                        type:
                          - string
                          - 'null'
                    required:
                      - about
                      - from
                      - page
                  proposed:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        domain:
                          type:
                            - string
                            - 'null'
                        found:
                          type: object
                          properties:
                            from:
                              type: string
                              enum:
                                - list
                                - records
                                - news
                                - web
                            source:
                              type:
                                - string
                                - 'null'
                            why:
                              type: string
                            url:
                              type:
                                - string
                                - 'null'
                          required:
                            - from
                            - source
                            - why
                            - url
                        verdict:
                          type: string
                          enum:
                            - rival
                            - supplier
                            - different_buyer
                            - different_product
                            - same_name
                            - unclear
                        sells:
                          type:
                            - string
                            - 'null'
                        to:
                          type:
                            - string
                            - 'null'
                        where:
                          type:
                            - string
                            - 'null'
                        shows:
                          type:
                            - object
                            - 'null'
                          properties:
                            words:
                              type: string
                            page:
                              type: string
                          required:
                            - words
                            - page
                        reads:
                          type: array
                          items:
                            type: object
                            properties:
                              model:
                                type: string
                              verdict:
                                type: string
                                enum:
                                  - rival
                                  - supplier
                                  - different_buyer
                                  - different_product
                                  - same_name
                                  - unclear
                              why:
                                type: string
                            required:
                              - model
                              - verdict
                              - why
                        overlap:
                          type:
                            - object
                            - 'null'
                          properties:
                            codes:
                              type: array
                              items:
                                type: string
                            towns:
                              type: array
                              items:
                                type: string
                            terms:
                              type: array
                              items:
                                type: string
                            supported:
                              type: boolean
                          required:
                            - codes
                            - towns
                            - terms
                            - supported
                        why:
                          type: string
                        rival:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                          required:
                            - id
                            - name
                        state:
                          type: string
                          enum:
                            - proposed
                            - confirmed
                            - struck
                        added:
                          type: boolean
                      required:
                        - name
                        - domain
                        - found
                        - verdict
                        - sells
                        - to
                        - where
                        - shows
                        - reads
                        - overlap
                        - why
                        - rival
                        - state
                        - added
                  left_out:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        domain:
                          type:
                            - string
                            - 'null'
                        found:
                          type: object
                          properties:
                            from:
                              type: string
                              enum:
                                - list
                                - records
                                - news
                                - web
                            source:
                              type:
                                - string
                                - 'null'
                            why:
                              type: string
                            url:
                              type:
                                - string
                                - 'null'
                          required:
                            - from
                            - source
                            - why
                            - url
                        verdict:
                          type: string
                          enum:
                            - rival
                            - supplier
                            - different_buyer
                            - different_product
                            - same_name
                            - unclear
                        sells:
                          type:
                            - string
                            - 'null'
                        to:
                          type:
                            - string
                            - 'null'
                        where:
                          type:
                            - string
                            - 'null'
                        shows:
                          type:
                            - object
                            - 'null'
                          properties:
                            words:
                              type: string
                            page:
                              type: string
                          required:
                            - words
                            - page
                        reads:
                          type: array
                          items:
                            type: object
                            properties:
                              model:
                                type: string
                              verdict:
                                type: string
                                enum:
                                  - rival
                                  - supplier
                                  - different_buyer
                                  - different_product
                                  - same_name
                                  - unclear
                              why:
                                type: string
                            required:
                              - model
                              - verdict
                              - why
                        overlap:
                          type:
                            - object
                            - 'null'
                          properties:
                            codes:
                              type: array
                              items:
                                type: string
                            towns:
                              type: array
                              items:
                                type: string
                            terms:
                              type: array
                              items:
                                type: string
                            supported:
                              type: boolean
                          required:
                            - codes
                            - towns
                            - terms
                            - supported
                        why:
                          type: string
                      required:
                        - name
                        - domain
                        - found
                        - verdict
                        - sells
                        - to
                        - where
                        - shows
                        - reads
                        - overlap
                        - why
                  decided:
                    type: array
                    items:
                      type: object
                      properties:
                        rival:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                          required:
                            - id
                            - name
                        state:
                          type: string
                          enum:
                            - confirmed
                            - struck
                      required:
                        - rival
                        - state
                  not_tested:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        domain:
                          type:
                            - string
                            - 'null'
                        found:
                          type: object
                          properties:
                            from:
                              type: string
                              enum:
                                - list
                                - records
                                - news
                                - web
                            source:
                              type:
                                - string
                                - 'null'
                            why:
                              type: string
                            url:
                              type:
                                - string
                                - 'null'
                          required:
                            - from
                            - source
                            - why
                            - url
                        why:
                          type: string
                      required:
                        - name
                        - domain
                        - found
                        - why
                  sources:
                    type: array
                    items:
                      type: object
                      properties:
                        from:
                          type: string
                          enum:
                            - list
                            - records
                            - news
                            - web
                        looked:
                          type: boolean
                        found:
                          type: integer
                        why:
                          type:
                            - string
                            - 'null'
                      required:
                        - from
                        - looked
                        - found
                        - why
                  cost:
                    type: object
                    properties:
                      usd:
                        type: number
                      model_calls:
                        type: integer
                      searches:
                        type: integer
                      pages:
                        type: integer
                    required:
                      - usd
                      - model_calls
                      - searches
                      - pages
                  asked_today:
                    type: integer
                  limit:
                    type:
                      - integer
                      - 'null'
                required:
                  - company
                  - target
                  - proposed
                  - left_out
                  - decided
                  - not_tested
                  - sources
                  - cost
                  - asked_today
                  - limit
        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/targets/northwind-dental/rivals/find' \
              -H "Authorization: Bearer $PODDATA_API_KEY" \
              -H 'Content-Type: application/json' \
              -d '{"list":[{"name":"Bluebird Dental","domain":"bluebird-dental.example"},{"name":"Summit Dental Supply","domain":"summit-dental-supply.example"}],"from":["list"]}'
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.