---
title: "Semantic search over the caller's prospects (lean summaries + progressive cursor)."
method: GET
path: "/api/v1/prospects/search"
tags: ["prospects"]
---

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

`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`)

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.

## Query parameters

- `q` string, required
- `limit` integer
- `cursor` string

## Response `200`

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

- ProspectSummaryList: A capped page of lean search summaries with progressive-cursor pagination.
  - `prospects` ProspectSummary[], required: The lean company summaries on this page.
    - `domain` string, required: The company's primary website domain. Use it to fetch the full record.
    - `name` string, nullable: The company's name.
    - `industry` string, nullable: The company's primary industry.
    - `company_size` 'micro' | 'small' | 'medium' | 'large' | 'enterprise' | 'null', nullable: Company size bucket by employee headcount (lowercase; null when undetermined). `micro` (≤10 employees), `small` (≤50), `medium` (≤200), `large` (≤500), `enterprise` (500+). Uses the SAME lowercase tokens as the `company_sizes` INPUT filter (DiscoveryCriteria.company_sizes), so a value read off a result can be re-submitted verbatim as a filter without a 400. `micro` companies are returned by a `small` `company_sizes` filter.
    - `headquarters_location` string, nullable: Headquarters location as a "City, Country" string.
    - `country` string, nullable: The company's country.
    - `city` string, nullable: The company's city.
    - `employee_count` integer, nullable: Estimated number of employees.
    - `logo_url` string, uri, nullable: Company logo/image URL.
    - `description` string, nullable: Short teaser, capped at 200 Unicode characters (never split mid-character). When the source description exceeds the cap it is cut at a word boundary and an ellipsis (…) is appended, so a shortened teaser is always visibly marked as truncated.
    - `semantic_score` number, nullable: Blended relevance score for this search result.
  - `total` integer: 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_id` string: The authenticated tenant.
  - `query` string: Echo of the `q` that produced this page.
  - `has_more` boolean: True when another page exists above the relevance floor. False means you have seen everything relevant — stop paging.
  - `next_cursor` string, nullable: Opaque cursor for the next page (pass back as `cursor`); null at the terminus.
  - `truncated` boolean, nullable: True when a hard item/byte cap dropped rows from THIS page (distinct from `has_more`, which signals whether more pages remain).

## Other responses

- `400`: Malformed request (missing/invalid field or header).
- `401`: Missing/invalid/expired Bearer token.
- `405`: HTTP method not allowed on this endpoint (rejected before any credit debit).
- `429`: Rate limit exceeded (100 requests / 60s per customer).

---

[API](https://skmtc.dev/prosp/apis/prosp-discovery-api.md) · [All operations](https://skmtc.dev/prosp/apis/prosp-discovery-api/llms.txt) · [OpenAPI document](https://skmtc.dev/prosp/apis/prosp-discovery-api/revisions/1f2e0c55da22?raw)