ProspectAPIs Meta API

openapi: 3.2.0
info:
  title: ProspectAPIs Meta 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: Meta
  description: 'Keyless endpoints: the price list and liveness.'
paths:
  /pricing:
    get:
      tags:
      - Meta
      summary: Live price list
      description: The live price list the whole product renders from, so no page can advertise a price the API is not charging. Free, no key.
      operationId: getPricing
      security: []
      responses:
        '200':
          description: The current prices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pricing'
              example:
                currency: usd
                signup_credit_usd: 1
                topup_bonus_tiers:
                - min_usd: 2000
                  bonus_pct: 120
                - min_usd: 500
                  bonus_pct: 60
                - min_usd: 100
                  bonus_pct: 25
                funding:
                  price_per_record_usd: 0.009
                  free_records_per_month: 0
                research:
                  available: true
                  price_per_research_usd: 0.15
                email_verification:
                  available: true
                  price_per_check_usd: 0.003
                  charged_statuses:
                  - valid
                  - invalid
                  free_statuses:
                  - catch-all
                  - unknown
                  max_emails_per_request: 25
                  quick_price_per_check_usd: 0.001
                  quick_charged_statuses:
                  - valid
                  - invalid
                  - catch-all
                  - unknown
                  domain_lookup:
                    price_usd: 0
                    lookups_per_hour: 300
                watchlists:
                  price_per_delivered_record_usd: 0.009
                  free_records_apply: false
                people_reads:
                  available: true
                  price_per_read_usd: 0.012
                  routes:
                  - GET /v1/people/profile
                  - POST /v1/people/search
                  - GET /v1/people/posts
                  - GET /v1/posts/engagers
                  - GET /v1/posts/resharers
                  - GET /v1/pages/followers
                  - GET /v1/pages/profile
                  available_routes:
                  - GET /v1/people/profile
                  - POST /v1/people/search
                  - GET /v1/people/posts
                  - GET /v1/posts/engagers
                  - GET /v1/pages/followers
                  - GET /v1/pages/profile
                  freshness: Each call fetches the person or page fresh at request time, not from a stored cache.
                companies:
                  available: false
                  price_per_company_usd: 0.02
                  free_statuses:
                  - building (202)
                  - several companies with that name (300)
                  - unresolvable (404)
                  - no company with that name (404)
                  routes:
                  - GET /v1/companies/:domain
                  available_routes: []
                ads:
                  available: false
                  price_per_platform_usd: 0.006
                  price_per_delivered_event_usd: 0.006
                  charged_statuses:
                  - ok
                  free_statuses:
                  - no_ads
                  - not_resolved
                  - not_covered
                  - unreadable
                  platforms:
                  - platform: meta
                    coverage: 'Worldwide: active ads in every country; inactive ads only when they reached the EU.'
                  - platform: google
                    coverage: 'Worldwide: verified advertisers'' ads shown in the last 30 days, live when shown in the last 2.'
                  - platform: linkedin
                    coverage: Ads run since 2023-06-01, kept a year after their last impression; run dates and reach only for ads shown in the EU.
                  - platform: tiktok
                    coverage: Only ads shown in the EEA, Switzerland and the UK, in the last 30 days.
                  routes:
                  - GET /v1/ads
                  - GET /v1/ads/:id
                  available_routes: []
                people_writes:
                  available: true
                  prices_usd:
                    POST /v1/messages: 0.03
                    POST /v1/people/invite: 0.03
                    POST /v1/people/invite/withdraw: 0.01
                    POST /v1/people/follow: 0.01
                    POST /v1/people/visit: 0.01
                    POST /v1/posts: 0.05
                    POST /v1/posts/react: 0.005
                    POST /v1/posts/comment: 0.02
                    POST /v1/posts/repost: 0.01
                    POST /v1/posts/quote: 0.02
                  routes:
                  - POST /v1/messages
                  - POST /v1/people/invite
                  - POST /v1/people/invite/withdraw
                  - POST /v1/people/follow
                  - POST /v1/people/visit
                  - POST /v1/posts
                  - POST /v1/posts/react
                  - POST /v1/posts/comment
                  - POST /v1/posts/repost
                  - POST /v1/posts/quote
                  available_routes:
                  - POST /v1/messages
                  - POST /v1/people/invite
                  - POST /v1/people/invite/withdraw
                  - POST /v1/people/follow
                  - POST /v1/people/visit
                  - POST /v1/posts
                  - POST /v1/posts/react
                  - POST /v1/posts/comment
                  - POST /v1/posts/repost
                  - POST /v1/posts/quote
                messaging_reads:
                  available: false
                  price_per_read_usd: 0.01
                  routes:
                  - GET /v1/messages
                  - GET /v1/messages/thread
                  available_routes: []
                launches:
                  available: false
                  price_per_record_usd: null
                  free_statuses:
                  - no match (200, empty)
                  - not found (404)
                  routes:
                  - GET /v1/launches
                  - GET /v1/launches/:id
                  available_routes: []
                  precision:
                    bar: 281 of 300 billable-correct (Wilson 95% lower bound 90% or more)
                    labelled: 0
                    billable_correct: 0
                    wilson_lower_95: null
                    label_date: null
                    met: false
                byoa:
                  available: true
                  connect_price_usd: 0
                  note: Connecting your own account is free; you pay only for the actions you run.
        '500':
          $ref: '#/components/responses/InternalError'
      x-agentic-access:
        action-class: connected
        consequence: read
        subject: optional
        token:
          max-ttl: 3600
        audit: none
  /health:
    get:
      tags:
      - Meta
      summary: Liveness
      description: Liveness for uptime monitors. Never fails on the database. Free, no key.
      operationId: getHealth
      security: []
      responses:
        '200':
          description: The service is up.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
              example:
                status: status
                stale_holds: 1
                stale_hold_minutes: 1
        '500':
          $ref: '#/components/responses/InternalError'
      x-agentic-access:
        action-class: connected
        consequence: read
        subject: optional
        token:
          max-ttl: 3600
        audit: none
components:
  schemas:
    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
    Health:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          description: ok.
        stale_holds:
          description: Count of holds older than the release cutoff, or "unknown".
          type:
          - integer
          - string
        stale_hold_minutes:
          type: integer
    Pricing:
      type: object
      properties:
        currency:
          description: usd.
          type: string
        signup_credit_usd:
          description: The one-time balance every new account starts with. No card, no monthly reset.
          type: number
        topup_bonus_tiers:
          type: array
          items:
            type: object
            properties:
              min_usd:
                type: integer
              bonus_pct:
                type: integer
        funding:
          type: object
          properties:
            price_per_record_usd:
              type: number
            free_records_per_month:
              description: 0 since 2026-10-25.
              type: integer
            coverage:
              description: 'What the funding data covers: complete_from (the date from which every announced round is held), partial (date ranges held in part) and a one-line note. The same object rides on an empty GET /v1/funding answer.'
              type: object
              properties:
                complete_from:
                  type: string
                  format: date
                partial:
                  type: array
                  items:
                    type: object
                    properties:
                      from:
                        type: string
                        format: date
                      to:
                        type: string
                        format: date
                note:
                  type: string
        research:
          type: object
          properties:
            available:
              type: boolean
            price_per_research_usd:
              type: number
        email_verification:
          type: object
          properties:
            available:
              type: boolean
            price_per_check_usd:
              type: number
            charged_statuses:
              description: Result statuses that are charged.
              type: array
              items:
                type: string
            free_statuses:
              description: Result statuses that are never charged.
              type: array
              items:
                type: string
            max_emails_per_request:
              type: integer
            quick_price_per_check_usd:
              type: number
            quick_charged_statuses:
              type: array
              items:
                type: string
            domain_lookup:
              type: object
              properties:
                price_usd:
                  type: integer
                lookups_per_hour:
                  type: integer
        watchlists:
          type: object
          properties:
            price_per_delivered_record_usd:
              type: number
            free_records_apply:
              description: 'false since 2026-10-25: deliveries are paid from the balance.'
              type: boolean
            linkedin:
              description: 'LinkedIn change watchlists: a price per delivered change plus a fee per watched person or page per UTC day. available is false until the family is on sale.'
              type: object
              properties:
                available:
                  type: boolean
                price_per_delivered_change_usd:
                  type: number
                price_per_watched_entity_day_usd:
                  type: number
        people_reads:
          description: The live people and page reads. One published per-read price; `available` follows the go-live switch, the same way research follows its price.
          type: object
          properties:
            available:
              description: Whether the live reads are on sale yet.
              type: boolean
            price_per_read_usd:
              description: The published price of one live read.
              type: number
            routes:
              description: The five live-read routes.
              type: array
              items:
                type: string
            available_routes:
              type: array
              items:
                type: string
            freshness:
              description: A plain note that each call fetches fresh at request time.
              type: string
        companies:
          type: object
          properties:
            available:
              type: boolean
            price_per_company_usd:
              type: number
            free_statuses:
              type: array
              items:
                type: string
            routes:
              type: array
              items:
                type: string
            available_routes:
              type: array
              items: {}
        ads:
          description: 'The ads library: one price per library that returns ads (status ok), and one per delivered ads watchlist event.'
          type: object
          properties:
            available:
              type: boolean
            price_per_platform_usd:
              type: number
            price_per_delivered_event_usd:
              type: number
            charged_statuses:
              type: array
              items:
                type: string
            free_statuses:
              type: array
              items:
                type: string
            platforms:
              type: array
              items:
                type: object
                properties:
                  platform:
                    type: string
                  coverage:
                    type: string
            routes:
              type: array
              items:
                type: string
            available_routes:
              type: array
              items: {}
        people_writes:
          type: object
          properties:
            available:
              type: boolean
            prices_usd:
              type: object
              properties:
                POST /v1/messages:
                  type: number
                  example: 0.03
                POST /v1/people/invite:
                  type: number
                  example: 0.03
                POST /v1/people/invite/withdraw:
                  type: number
                  example: 0.01
                POST /v1/people/follow:
                  type: number
                  example: 0.01
                POST /v1/people/visit:
                  type: number
                  example: 0.01
                POST /v1/posts:
                  type: number
                  example: 0.05
                POST /v1/posts/react:
                  type: number
                  example: 0.005
                POST /v1/posts/comment:
                  type: number
                  example: 0.02
                POST /v1/posts/repost:
                  type: number
                  example: 0.01
                POST /v1/posts/quote:
                  type: number
                  example: 0.02
                POST /v1/invitations/accept:
                  type: number
                  example: 0.005
                POST /v1/invitations/decline:
                  type: number
                  example: 0.005
                POST /v1/connections/remove:
                  type: number
                  example: 0.005
                POST /v1/posts/edit:
                  type: number
                  example: 0.02
                POST /v1/posts/delete:
                  type: number
                  example: 0.02
                POST /v1/posts/comment/delete:
                  type: number
                  example: 0.02
                POST /v1/people/endorse:
                  type: number
                  example: 0.005
                POST /v1/chats:
                  type: number
                  example: 0.03
                POST /v1/messages/react:
                  type: number
                  example: 0.005
                POST /v1/messages/read:
                  type: number
                  example: 0.005
              description: The price in USD of each write route, keyed by route.
              additionalProperties: false
            routes:
              type: array
              items:
                type: string
            available_routes:
              type: array
              items:
                type: string
        messaging_reads:
          type: object
          properties:
            available:
              type: boolean
            price_per_read_usd:
              type: number
            routes:
              type: array
              items:
                type: string
            available_routes:
              type: array
              items: {}
        launches:
          type: object
          properties:
            available:
              type: boolean
            price_per_record_usd:
              type: 'null'
            free_statuses:
              type: array
              items:
                type: string
            routes:
              type: array
              items:
                type: string
            available_routes:
              type: array
              items: {}
            precision:
              type: object
              properties:
                bar:
                  type: string
                labelled:
                  type: integer
                billable_correct:
                  type: integer
                wilson_lower_95:
                  type: 'null'
                label_date:
                  type: 'null'
                met:
                  type: boolean
        byoa:
          type: object
          properties:
            available:
              type: boolean
            connect_price_usd:
              type: integer
            note:
              type: string
        hiring_tech:
          description: 'Hiring and tech-stack signals: one price per lookup whose status is ok (GET /v1/companies/{domain}/jobs and /technologies).'
          type: object
          properties:
            available:
              type: boolean
            price_per_lookup_usd:
              type: number
            charged_statuses:
              type: array
              items:
                type: string
            free_statuses:
              type: array
              items:
                type: string
            routes:
              type: array
              items:
                type: string
            available_routes:
              type: array
              items: {}
        events:
          description: 'Event discovery: one price per event returned, and one per delivered events watchlist event; the city catalog is free. Event enrichment: one price per enriched event with at least one ok section.'
          type: object
          properties:
            available:
              type: boolean
            price_per_event_usd:
              type: number
            price_per_delivered_event_usd:
              type: number
            platforms:
              type: array
              items:
                type: string
            routes:
              type: array
              items:
                type: string
            available_routes:
              type: array
              items: {}
            price_per_enriched_event_usd:
              type: number
        website_contacts:
          description: 'Website contact discovery (POST /v1/website/contacts): the people and addresses a company''s own site lists. available follows the go-live switch; price_per_contact_usd is charged per contact returned with a usable address.'
          type: object
          properties:
            available:
              type: boolean
            routes:
              type: array
              items:
                type: string
            available_routes:
              type: array
              items: {}
            price_per_contact_usd:
              type: number
              description: USD per contact returned with a usable address.
        follower_enrichment:
          description: 'Enriched page followers (GET /v1/pages/followers/enriched): each follower joined to a live profile read. available follows the go-live switch; price_per_enriched_follower_usd is charged per follower returned with its profile.'
          type: object
          properties:
            available:
              type: boolean
            routes:
              type: array
              items:
                type: string
            available_routes:
              type: array
              items: {}
            price_per_enriched_follower_usd:
              type: number
              description: USD per follower returned with its profile (enrichment status ok).
            max_per_call:
              type: integer
              description: The most followers one call enriches.
            charged_statuses:
              type: array
              items:
                type: string
            free_statuses:
              type: array
              items:
                type: string
        lead_search:
          description: 'Lead and account search (POST /v1/leads/search, POST /v1/leads/companies/search). Held: available is false until the family goes live; priced per result returned.'
          type: object
          properties:
            available:
              type: boolean
            routes:
              type: array
              items:
                type: string
            available_routes:
              type: array
              items: {}
            price_per_result_usd:
              type:
              - number
              - 'null'
              description: USD per result returned; an empty search is free.
  responses:
    InternalError:
      description: An unexpected server error; nothing was charged. Retry shortly.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Internal server error
  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