### POST /api/v4/{collection}/search

**Search records** (`search`). Find records with a filter, an explicit sort, or semantic ranking (startups). Pages shrink to fit 1 MB; continue by sending only page.next_cursor.

1¢ per successful request. API key required. Success: `200`.

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `collection` | "startups" \| "investors" \| "funding_rounds" \| "exits" | yes | startups, investors, funding_rounds or exits. |

#### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `filter` | object |  | v4 filter object. Sibling keys AND; see the Filters guide. |
| `query` | string |  | Startups only: rank by meaning (semantic search). Replaces sort. |
| `similar_to` | string |  | Startups only: rank look-alikes of this startup (domain or UUID). Replaces sort. |
| `sort` | array<string> |  | Up to three field names; prefix "-" for descending. NULL sorts last; id breaks ties. |
| `fields` | array<string> |  | Fields to return. Omit for the default fields. id is always returned. |
| `expand` | array<string> |  | Related records to nest, e.g. ["funding_rounds","investors"]. See /schema for per-record caps. |
| `focus` | object |  | Investors only: rank by sector specialisation, e.g. {"industries":["fintech"]}. Adds focus_count, focus_total, focus_share, focus_score. |
| `limit` | integer |  | Rows per page, 1–100 (default 25). Pages also shrink to fit 1 MB. |
| `cursor` | string |  | page.next_cursor from the previous page. Send only the cursor (and optionally limit) to continue. |

#### Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array<object> | yes | A record with the requested fields (see /schema). Expanded to-many relations are page objects {data, page}; to-one relations are objects or null. |
| `data[].id` | string | yes | UUID. |
| `page` | object | yes | Pagination; see the Pagination guide. |
| `page.next_cursor` | string \| null | yes | Send it back (alone, optionally with limit) for the next page; null at the end. |
| `page.total` | object |  | How many records match in total. |
| `page.total.value` | integer \| null | yes | Number of matching records; null when unknown. |
| `page.total.exact` | boolean | yes | false when value is a lower bound (≥10,000) or unknown. |
| `page.shortened` | true |  | Present when the page was cut to fit 1 MB; next_cursor continues exactly after the last row. |
| `meta.request_id` | string | yes | Request id (also in X-Request-Id). |
| `meta.cost_usd_cents` | number | yes | Charged for this request, in USD cents. |
| `meta.applied_filter` | object \| null | yes | The filter that ran, after normalisation, in v4 grammar. |
| `meta.search_id` | string \| null |  | Semantic searches: handle for POST /exports {search_id}; valid 30 minutes. |
| `meta.search_expires_at` | string |  | ISO 8601 timestamp (UTC). |
| `meta.ranking` | object |  | Semantic searches only. Ranking is approximate and never exhaustive. |
| `meta.ranking.type` | "semantic" | yes |  |
| `meta.ranking.coverage` | "within_filter" \| "post_filtered" \| null | yes | within_filter: every startup the filter allows was ranked. post_filtered: more than 10,000 startups matched, so ranking is approximate; strong matches can be missed. |
| `meta.ranking.population` | number \| null | yes | Startups the filter allows (when known). |
| `meta.ranking.ranked` | number \| null | yes | Candidates that were ranked. |
| `meta.ranking.unranked` | number \| null | yes | Allowed startups without a semantic profile, so not ranked. |
| `meta.ranking.dropped` | number | yes | Ranked rows on this page that no longer exist. |
| `meta.focus` | object |  | Investors with focus: the sectors and how focus_score ranks them. |
| `meta.diagnostics` | any |  | For empty results: which conditions removed the most records. |
| `meta.match_scope` | string |  | Investors: independent_firm_facets when stage, sector and geography are matched separately, not as one joint strategy. |

#### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. |
| 400 | `UNKNOWN_FIELD` | A field name is not part of this collection. |
| 400 | `OPERATOR_NOT_SUPPORTED` | The operator is not available for this field. |
| 400 | `TAG_ARRAY_NEEDS_OPERATOR` | A bare array was given for a tag field. |
| 400 | `VALUE_UNKNOWN` | A filter value does not match any known value. |
| 400 | `VALUE_AMBIGUOUS` | A friendly filter value matches several canonical values. |
| 400 | `QUERY_TOO_COMPLEX` | The filter exceeds the complexity limits. |
| 400 | `SEMANTIC_NOT_SUPPORTED` | Semantic ranking (query / similar_to) is only available for startups. |
| 400 | `CURSOR_INVALID` | The cursor is malformed, belongs to another query or another account. |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. |
| 410 | `CURSOR_EXPIRED` | The cursor expired (24 h, or 30 min for semantic rankings). |
| 413 | `RECORD_TOO_LARGE` | A single record exceeds the 1 MB response budget. |
| 429 | `RATE_LIMITED` | Too many requests in the current window. |
| 429 | `QUOTA_EXCEEDED` | A daily or concurrency quota is used up. |
| 500 | `INTERNAL_ERROR` | An unexpected server error. |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. |
| 504 | `QUERY_TIMEOUT` | The query ran out of its time budget. |

#### Example

```bash

curl -X POST 'https://startup-seeker.com/api/v4/startups/search' \
  -H "Authorization: Bearer $STARTUPSEEKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "hq_country": "DE",
      "industries": {
        "any": [
          "fintech"
        ]
      },
      "total_funding_usd": {
        "gte": 1000000
      }
    },
    "fields": [
      "name",
      "domain",
      "total_funding_usd"
    ],
    "sort": [
      "-total_funding_usd"
    ],
    "limit": 2
  }'

```