prospects

Semantic search over the caller's prospects (lean summaries + progressive cursor).

Returns LEAN prospect summaries (~11 customer-safe fields) — not the full record — so the response can never exceed the client token budget. To read every field for one company, call GET /api/v1/prospects/{domain} with a summary's domain.

Pagination is a progressive OPAQUE cursor: omit cursor for the first page, then pass the previous response's next_cursor back verbatim to fetch the next. Treat it as opaque — do not parse or construct it (its encoding is an implementation detail); an unrecognized cursor safely restarts from the first page. has_more=false / next_cursor=null means you have seen everything above the relevance floor — stop.

get/api/v1/prospects/search

Request

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

Query parameters

qstring required

Free-text semantic query.

limitinteger

Page size for search (1–50, default 20). Deliberately smaller than the list limit; a value outside the range is rejected with a 400, not clamped.

cursorstring

Opaque progressive-pagination cursor. Omit for the first page; pass the previous response's next_cursor back verbatim to fetch the next. Treat it as an opaque token: do NOT parse it, construct it, or do arithmetic on it — its internal encoding is an implementation detail that may change without notice. An unrecognized or malformed cursor is safely treated as "start from the beginning" rather than rejected.

Response

A lean, capped page of ranked summaries (each carries a semantic_score).

totalinteger

PAGINATION count — the number of MATCHES for this query (relevance-floor-passing results), NOT the page length. Use it for a "showing X of N" label (X = prospects.length, N = total). When has_more is true because deep pagination hit the recall cap, total is a lower bound and has_more signals the unreached tail. This is a SEARCH result-set count, a DIFFERENT concept from a single discovery's delivery count (JobResult.total_prospects / JobStatus.total_prospects) — do not group the two together. (Contrast ProspectList.total, which is the same NAME but counts the rows in the returned page rather than all matches.)

customer_idstring

The authenticated tenant.

querystring

Echo of the q that produced this page.

has_moreboolean

True when another page exists above the relevance floor. False means you have seen everything relevant — stop paging.

next_cursorstring nullable

Opaque cursor for the next page (pass back as cursor); null at the terminus.

truncatedboolean nullable

True when a hard item/byte cap dropped rows from THIS page (distinct from has_more, which signals whether more pages remain).

Example response

{
  "prospects": [
    {
      "domain": "acme.de"
    }
  ]
}

Changes

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