discovery

Start a discovery job.

Debits 100 credits (the per-discovery cost) atomically and queues a discovery. The X-Idempotency-Key header is required; replaying the same key returns the original job with deduplicated: true and does not double-charge.

Concurrency limit. A tenant may run only a bounded number of discovery jobs at once. While you are at that limit a new execute is rejected with 429 and error: concurrent_limit — cancel or wait for a running job to finish, then retry. The credits for a rejected request are refunded, so a 429 never costs you credits (your balance nets to zero and no ledger entry is written for the rejected attempt).

Saturation pre-check (net-new estimate). Before charging, the service estimates how many new companies this exact ICP would yield for you (companies you do not already own from prior runs). When that estimate is ~0 and reliable — you have already discovered the addressable set for these criteria — the request is held with 409 and a status: saturation_warning body (see SaturationWarning) instead of running. No credits are charged and no job is started. To run it anyway, re-submit with parameters.acknowledge_low_yield: true; the acknowledged run charges normally and starts.

post/mcp/tools/execute

Request

  • Base URL: https://api.prosp.cc
  • URL: https://api.prosp.cc/mcp/tools/execute
  • Auth: OAuth 2 (client credentials, token URL https://prosp-mcp-641053169627.auth.eu-central-1.amazoncognito.com/oauth2/token, scopes: mcp/execute)

Headers

X-Idempotency-Keystring required

Client-generated key that makes execute safe to retry.

Request body

toolName'discovery' required

The tool to run. Use discovery to start a prospect discovery.

Example request

{
  "toolName": "discovery",
  "parameters": {
    "query": "Find retail partners in Europe",
    "industries": [
      "Retail",
      "Fashion"
    ],
    "locations": [
      "Germany",
      "Austria"
    ],
    "language": "de"
  }
}

Response

Job queued, OR the existing job when the request was de-duplicated — by a replayed idempotency key, or by a query-fingerprint match against a discovery you already started. A de-duplicated response carries deduplicated: true + reason and is NOT charged (the credit debit is refunded). Distinguish the two shapes via deduplicated.

OR

Example response

{
  "poll_after_seconds": 20,
  "estimated_duration_seconds": 2900,
  "estimated_duration_p50_seconds": 1140,
  "estimated_duration_p90_seconds": 2400,
  "estimated_duration_p95_seconds": 2900,
  "estimated_yield": 4
}

Changes

No recorded changes to this operation across all 1 revision of this API.