ProspectAPIs Ads API

openapi: 3.2.0
info:
  title: ProspectAPIs Ads API
  summary: Funding signals and cited prospect research over one REST API.
  description: 'The REST contract for ProspectAPIs: funding rounds you can filter and page, cited prospect research briefs, and funding watchlists that push new matches to a webhook. Built for sales teams and the AI agents that work for them.


    Authentication is a bearer API key (`Authorization: Bearer pa_live_`), created in the dashboard. `GET /pricing`, `GET /health` and `GET /v1/version` need no key.


    Every account starts with a one-time free balance (`signup_credit_usd` in `GET /pricing`), and every paid call draws from it at its own price: `GET /v1/funding` per returned record (a no-match is free), `POST /v1/email/verify` per valid or invalid result, `POST /v1/research` per completed brief. Paid responses carry `X-Credits-Remaining`. The live price list is `GET /pricing`; a key''s balance is `GET /v1/account`. This document describes shapes, not prices.'
  version: 0.1.0
  contact:
    name: ProspectAPIs
    url: https://prospectapis.com
    email: emma@prospectapis.com
  license:
    name: Proprietary
    url: https://prospectapis.com/terms
  termsOfService: https://prospectapis.com/terms
servers:
- url: https://api.prospectapis.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Ads
  description: A company's live ads on the public Meta, Google, LinkedIn and TikTok ad libraries, keyed on its domain.
paths:
  /v1/ads:
    get:
      tags:
      - Ads
      summary: Search a company's ads
      operationId: searchAds
      description: 'Whether a company runs ads now on the public Meta, Google, LinkedIn and TikTok ad libraries, by domain: a summary, a status per library (ok, no_ads, not_resolved, not_covered, unreadable) with the advertiser and how it was resolved, and the live ads, newest last seen first. Each library is read logged out and cached for a few hours. Costs $0.006 per library whose status is ok, on the first page; everything else is free. One unreadable library never fails the call; 503 SOURCE_UNAVAILABLE only when every library asked for is unreadable. Coverage: Meta worldwide (active ads; inactive ones only when they reached the EU); Google worldwide (the last 30 days); LinkedIn ads run since 2023-06-01, with run dates and reach only for ads shown in the EU; TikTok only ads shown in the EEA, Switzerland and the UK.'
      parameters:
      - name: domain
        in: query
        required: true
        schema:
          type: string
        example: acme.com
        description: The company's bare domain.
      - name: platform
        in: query
        required: false
        schema:
          type: string
        example: meta,google
        description: One or more of meta, google, linkedin, tiktok, comma separated. Omit for all four.
      - name: google_advertiser_id
        in: query
        required: false
        schema:
          type: string
          maxLength: 120
        description: Pin the Google advertiser (AR followed by digits).
      - name: meta_page_id
        in: query
        required: false
        schema:
          type: string
          maxLength: 120
        description: Pin the Facebook page by its numeric id.
      - name: linkedin_company_id
        in: query
        required: false
        schema:
          type: string
          maxLength: 120
        description: Pin the LinkedIn company by its numeric id.
      - name: tiktok_advertiser
        in: query
        required: false
        schema:
          type: string
          maxLength: 120
        description: Pin the TikTok advertiser by its name as the library shows it.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
        description: Ads per page, 1 to 100 (default 25).
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: next_cursor from the previous page. Later pages are free and come from the same read, never from a library the first page reported unreadable; a cursor works only with the key that made the first call and expires after 6 hours, and INVALID_CURSOR or STALE_CURSOR means repeat the call without it. A lookup that pins an advertiser id is one page (next_cursor null).
      responses:
        '200':
          description: Each library's status and the live ads (possibly none).
          headers:
            X-Credits-Remaining:
              $ref: '#/components/headers/X-Credits-Remaining'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdsList'
              example:
                domain: acme.com
                company_id: 6f0c2b1e-7a1d-4c55-9a3e-1b2c3d4e5f60
                summary:
                  running_now: true
                  platforms_running: 1
                  ads_live_total: 1
                  ads_live_is_lower_bound: true
                  first_seen_any: '2026-11-01'
                  newest_creative_at: '2026-11-01'
                  sentence: Running 412+ ads on Google and Meta, first seen 2025-11-04
                platforms:
                - platform: meta
                  status: ok
                  reason: reason
                  advertiser:
                    id: 6f0c2b1e-7a1d-4c55-9a3e-1b2c3d4e5f60
                    name: Jane Doe
                    page_url: https://acme.com
                  resolution:
                    method: caller_supplied
                    confidence: 0.9
                    evidence: evidence
                  ads_live: 1
                  ads_total_band: ads total band
                  complete: true
                  truncated: true
                  read_at: '2026-11-01T12:00:00Z'
                  cached: true
                  held: true
                  coverage: coverage
                data:
                - id: meta.1234567890
                  platform: meta
                  advertiser_name: advertiser name
                  advertiser_id: advertiser id
                  advertiser_url: https://acme.com
                  creative_text: creative text
                  media_urls:
                  - https://acme.com
                  first_seen: '2026-11-01T12:00:00Z'
                  last_seen: '2026-11-01T12:00:00Z'
                  countries:
                  - countries
                  landing_url: https://acme.com
                  status: active
                  format: video
                  source_url: https://acme.com
                  read_at: '2026-11-01T12:00:00Z'
                count: 1
                total: 1
                next_cursor: next cursor
                charged_usd: 0.006
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/AdsSourceUnavailable'
      x-price-usd: 0.006
      x-agentic-access:
        action-class: connected
        consequence: read-billed
        subject: optional
        token:
          max-ttl: 3600
        audit: billing-ledger
  /v1/ads/{id}:
    get:
      tags:
      - Ads
      summary: Get one ad
      operationId: getAd
      description: One ad in full by its id from GET /v1/ads, with the facts its library shows only on the single ad (for example the countries it ran in). Costs $0.006 when found; an unknown id is a free 404; a library that cannot be read is a free 503.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        example: meta.1234567890
        description: 'An ad id from GET /v1/ads: the platform and the platform''s own ad id, for example meta.1234567890.'
      responses:
        '200':
          description: The ad.
          headers:
            X-Credits-Remaining:
              $ref: '#/components/headers/X-Credits-Remaining'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Ad'
              example:
                data:
                  id: meta.1234567890
                  platform: meta
                  advertiser_name: advertiser name
                  advertiser_id: advertiser id
                  advertiser_url: https://acme.com
                  creative_text: creative text
                  media_urls:
                  - https://acme.com
                  first_seen: '2026-11-01T12:00:00Z'
                  last_seen: '2026-11-01T12:00:00Z'
                  countries:
                  - countries
                  landing_url: https://acme.com
                  status: active
                  format: video
                  source_url: https://acme.com
                  read_at: '2026-11-01T12:00:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/AdsSourceUnavailable'
      x-price-usd: 0.006
      x-agentic-access:
        action-class: connected
        consequence: read-billed
        subject: optional
        token:
          max-ttl: 3600
        audit: billing-ledger
components:
  responses:
    Unauthorized:
      description: The API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description: Out of credits. The body carries `top_up_url`; nothing was charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests; retry after the window.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was invalid (e.g. a bad filter or input); nothing was charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    AdsSourceUnavailable:
      description: Every library asked for is unreadable right now. No list is returned and nothing is charged. Retry after Retry-After seconds.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AdsUnavailable'
    NotFound:
      description: No such record for this account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    AdsPlatformRead:
      type: object
      description: One library's answer. status ok, no_ads, not_resolved, not_covered or unreadable; only no_ads is an authoritative empty, and only ok is charged.
      required:
      - platform
      - status
      properties:
        platform:
          type: string
          enum:
          - meta
          - google
          - linkedin
          - tiktok
        status:
          type: string
          enum:
          - ok
          - no_ads
          - not_resolved
          - not_covered
          - unreadable
        reason:
          type: string
          description: 'unreadable only: rate_limited, blocked, timeout, parse, platform_off, no_egress, reader_unavailable.'
        advertiser:
          type:
          - object
          - 'null'
          properties:
            id:
              type:
              - string
              - 'null'
            name:
              type:
              - string
              - 'null'
            page_url:
              type:
              - string
              - 'null'
        resolution:
          type:
          - object
          - 'null'
          description: How the advertiser was tied to the company.
          properties:
            method:
              type:
              - string
              - 'null'
              enum:
              - caller_supplied
              - website_link
              - landing_domain_majority
              - name_match
              - null
            confidence:
              type: number
            evidence:
              type: string
        ads_live:
          type: integer
          minimum: 0
        ads_total_band:
          type:
          - string
          - 'null'
          description: The library's own count or band, where it gives one.
        complete:
          type: boolean
        truncated:
          type: boolean
          description: 'More ads than one read takes: ads_live is a lower bound.'
        read_at:
          type: string
          format: date-time
        cached:
          type: boolean
        held:
          type: boolean
          description: A read that disagreed sharply with the last one is held until a second read agrees; the last applied read is shown.
        coverage:
          type:
          - string
          - 'null'
    AdsList:
      type: object
      required:
      - domain
      - summary
      - platforms
      - data
      - count
      - total
      - next_cursor
      - charged_usd
      properties:
        domain:
          type: string
        company_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The company record's id, when we hold one for the domain.
        summary:
          $ref: '#/components/schemas/AdsSummary'
        platforms:
          type: array
          items:
            $ref: '#/components/schemas/AdsPlatformRead'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Ad'
        count:
          type: integer
        total:
          type: integer
        next_cursor:
          type:
          - string
          - 'null'
        charged_usd:
          type: number
          description: What this call cost.
    AdsSummary:
      type: object
      properties:
        running_now:
          type: boolean
        platforms_running:
          type: integer
        ads_live_total:
          type: integer
        ads_live_is_lower_bound:
          type: boolean
        first_seen_any:
          type:
          - string
          - 'null'
          format: date
        newest_creative_at:
          type:
          - string
          - 'null'
          format: date
        sentence:
          type: string
          example: Running 412+ ads on Google and Meta, first seen 2025-11-04
    AdsUnavailable:
      allOf:
      - $ref: '#/components/schemas/Error'
      - type: object
        required:
        - platforms
        properties:
          platforms:
            type: array
            items:
              type: object
              properties:
                platform:
                  type: string
                  enum:
                  - meta
                  - google
                  - linkedin
                  - tiktok
                status:
                  const: unreadable
                reason:
                  type: string
    Ad:
      type: object
      description: One ad as its library shows it. A field the library does not show is null, never filled in.
      required:
      - id
      - platform
      - advertiser_name
      - advertiser_id
      - advertiser_url
      - creative_text
      - media_urls
      - first_seen
      - last_seen
      - countries
      - landing_url
      - status
      - format
      - source_url
      - read_at
      properties:
        id:
          type: string
          example: meta.1234567890
          description: 'Our id: the platform, a dot, and the library''s own id.'
        platform:
          type: string
          enum:
          - meta
          - google
          - linkedin
          - tiktok
        advertiser_name:
          type:
          - string
          - 'null'
        advertiser_id:
          type:
          - string
          - 'null'
          description: The library's id for the advertiser (a page id, an advertiser id, a company id). TikTok shows none.
        advertiser_url:
          type:
          - string
          - 'null'
          format: uri
        creative_text:
          type:
          - string
          - 'null'
          description: The ad's text. Google and TikTok list views show none.
        media_urls:
          type: array
          items:
            type: string
            format: uri
          description: Image and video URLs as the library serves them; some expire.
        first_seen:
          type:
          - string
          - 'null'
          format: date-time
          description: When the library says the ad started.
        last_seen:
          type:
          - string
          - 'null'
          format: date-time
          description: When the library says the ad was last shown.
        countries:
          type:
          - array
          - 'null'
          items:
            type: string
          description: ISO 3166-1 alpha-2 codes, where the library names them (often only on GET /v1/ads/{id}).
        landing_url:
          type:
          - string
          - 'null'
          format: uri
        status:
          type:
          - string
          - 'null'
          enum:
          - active
          - inactive
          - null
          description: Meta states it; for Google it is active when last shown within 2 days of the read; LinkedIn and TikTok state none.
        format:
          type:
          - string
          - 'null'
          example: video
        source_url:
          type: string
          format: uri
          description: The ad on its public library page.
        read_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When we read it from the library.
    Error:
      type: object
      required:
      - error
      description: Every error answers with this shape. `error` is a human-readable message; `code` is a stable machine code when present.
      properties:
        error:
          type: string
        code:
          type: string
          description: A stable error code, e.g. INVALID_FILTER, INVALID_INPUT, INVALID_ID, NOT_FOUND, INSUFFICIENT_CREDITS, WATCHLIST_LIMIT, RATE_LIMITED.
        message:
          type: string
          description: Extra guidance on some errors (401, 402).
        field:
          type: string
          description: The offending field, on some 400s.
        top_up_url:
          type: string
          format: uri
          description: Where to add credits, on a 402.
      additionalProperties: true
  headers:
    RateLimit-Limit:
      description: Requests this API key may make per minute.
      schema:
        type: integer
    RateLimit-Reset:
      description: Seconds until the current window resets.
      schema:
        type: integer
    RateLimit-Remaining:
      description: Requests left in the current one-minute window.
      schema:
        type: integer
    X-Credits-Remaining:
      description: USD credits left after this call settles.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key as a bearer token: `Authorization: Bearer pa_live_<48 hex>`. Create and manage keys in the dashboard at https://prospectapis.com.'
externalDocs:
  description: API reference and quickstart
  url: https://prospectapis.com/docs