Search, filter and export startups, investors, funding rounds and exits; enrich your own company lists; and keep them in saved lists. Every response is JSON with the same shape, every list pages the same way, and every job follows the same lifecycle.
REST base URL:https://startup-seeker.com/api/v4
Authentication:Authorization: Bearer ssk_live_… with a key from your API settings.
AI assistants: connect Claude, ChatGPT or Cursor to https://startup-seeker.com/mcp/v4; it speaks the same filters. See Using with AI agents.
Create and revoke keys at /account/api-keys. Keys start with ssk_live_; keep them server-side.
GET /schema, GET /schema/{collection}, GET /industries, /api/v4/openapi.json and the docs need no key.
API keys and connected AI apps (OAuth) share your account's balance and quotas.
A missing, invalid or revoked key returns 401 UNAUTHORIZED.
Records and collections
Collection
One record is
Refs accepted by GET /{collection}/{ref}
startups
a company
UUID, domain, slug, LinkedIn URL
investors
a VC firm, angel group, corporate or accelerator
UUID, domain, slug, LinkedIn URL
funding_rounds
an accepted funding round
UUID
exits
an acquisition or IPO
UUID
Fields:fields: ["name", "domain"] returns only those (plus id). Without fields, the default set is returned. GET /schema/{collection} lists every field with its type, meaning and filter operators.
Identity:id is stable. When two records are merged, the old ref resolves to the survivor, which carries merged_from.
Unknown, empty, not requested:null means unknown; [] means known to be empty; a field you did not request is absent.
Many refs at once:POST /{collection}/match takes up to 100 domains, UUIDs, LinkedIn URLs or names and answers per input, in order: exact, candidates, not_found or invalid. Names always return candidates, never an exact match, so you choose.
Filters
A filter is a JSON object. Sibling keys combine with AND. A field maps to a value (equality) or to an object of operators (which also AND).
and, or, not and text are reserved keys. and and or take arrays of filter objects; not takes one.
Value forms
You write
Scalar field (e.g. hq_country)
Tag field (e.g. industries)
"x", a number or true
equals x
contains x
["a", "b"]
is one of a, b
errorTAG_ARRAY_NEEDS_OPERATOR: write {"any": [...]} or {"all": [...]}
{"gte": 1, "lt": 5}
operators (AND)
operators
null, {} or []
error: use {"exists": false} for unknown values
error
Operators
Operator
Meaning
Works on
eq, ne
equals / has a value other than
text, numbers, dates, enums
gt, gte, lt, lte, between
comparisons; between: [low, high] is inclusive
numbers, money, dates
in, nin
is one of / has a value that is none of
text, numbers, enums, ids
prefix
starts with
text
match
full-text words: "\"sodium ion\" OR \"na ion\" -lithium"
text
any, all, none
contains any / all / none of
tags
exists
true: has a value; false: unknown
scalar fields (tags use empty)
empty
true: unknown or []; false: at least one value
tags
some, count, role
related records, see below
relations
/schema/{collection} lists the operators each field supports. Anything else returns OPERATOR_NOT_SUPPORTED with the list.
Unknown values (NULL)
Condition
Field unknown
Field []
Field has a value
eq, gt, in, any, all, match, prefix
no match
no match
evaluated
ne, nin
no match (only known values)
—
evaluated
none
no match
match
evaluated
exists: true / false (scalar fields)
no / match
—
match / no
empty: true
match
match
no
not: {…}
the complement: includes unknown
complement
complement
So {"status": {"ne": "active"}} means "known and not active", while {"not": {"status": "active"}} means "anything but active, including unknown". Missing total_funding_usd is unknown, not zero.
Related records
{"investors": "sequoiacap.com"} or {"investors": {"in": ["sequoiacap.com", "a16z.com"]}}: linked to any of these investors (domain or UUID). Add "role": "lead" for lead investors only.
{"funding_rounds": {"some": {"round_type": "seed", "amount_usd": {"gte": 1000000}}}}: at least one round matches all conditions. Two separate some clauses (inside and) may be met by different rounds.
{"portfolio": {"count": {"gte": 5}, "some": {"hq_country": "BE"}}} (investors): at least 5 distinct portfolio startups match. deals works the same for funding rounds and accepts role.
Funding rounds and exits: {"startup": {"some": {"hq_country": "FR"}}} filters by the linked startup.
Friendly values
Field
You can write
Becomes
dates
"-30d", "-12m", "-2y", "today"
a UTC date, frozen when the first page runs
hq_country
"DE", "Germany", "DEU"
"DE"
hq_city
"Berlin", "New York", a GeoNames id
GeoNames ids; other cities: GET /locations?q=…
industries
a slug, a label like "Battery Technology", or a group "group:climate"
slugs; see GET /industries
stages (investors)
"Series A", "pre seed"
"series a", "pre-seed"
A value that matches exactly one canonical value is converted. Several matches return VALUE_AMBIGUOUS with candidates, and no match returns VALUE_UNKNOWN with did_you_mean. Nothing is silently widened: "Series D" is unknown (investor stages stop at series c+), and "climate" must be written as "group:climate". The normalised filter is echoed in meta.applied_filter.
Text search
"text": "embedded payments -crypto" (or {"match": "…"}) searches startup name and description (investors: name and thesis; rounds and exits: the linked startup). It matches whole words without stemming; use OR for variants and -word to exclude. For topics, semantic search usually works better.
Limits
Up to 3 nesting levels, 30 conditions, 100 values per array and a 16 KB body. Larger filters return QUERY_TOO_COMPLEX.
Next page: send only the cursor, plus an optional new limit: POST /startups/search {"cursor": "c1.a.…"}. On GET lists, use ?cursor=…. The cursor carries the original filter, sort, fields and expands. Sending other parameters with a cursor is an error.
End:next_cursor is null.
Page size:limit 1–100 (default 25). Pages also shrink to fit the 1 MB response budget; then page.shortened is true, and the cursor continues exactly after the last row returned. Nothing is skipped or repeated.
Cursor lifetime: 24 hours (semantic searches: 30 minutes). An expired cursor returns 410 CURSOR_EXPIRED; run the query again. Cursors are bound to your account; a changed or foreign cursor returns 400 CURSOR_INVALID.
Live pages: pages read live data, so records updated between pages can move. Use an export for one consistent read.
Totals:{"value": 178, "exact": true}. Beyond 10,000 matches, {"value": 10000, "exact": false} means "at least". {"value": null, "exact": false} means the count did not finish in time. For exact large counts, use POST /{collection}/aggregate.
Expand related records
expand nests related records into each result, e.g. "expand": ["funding_rounds", "investors"] on startups or ?expand=portfolio on an investor.
To-many relations are page objects, so a partial relation describes itself:
Continue with GET /startups/{id}/funding_rounds?cursor=….
To-one relations (startup and acquirer on rounds and exits) are plain objects or null.
Caps: each relation returns up to its per-record cap (listed under expand in /schema; for example 20 funding rounds and 25 investors), and at most 2,000 related records per response.
Order: funding rounds are newest first; a portfolio is alphabetical; co-investors are ordered by shared deals.
Sources:expand: ["sources"] adds the public evidence behind the record's fields (URL, field, date), with the fields you requested first. Sources show where a value came from; they are not a guarantee that every field is sourced.
Related records as fields: relation names are not fields; fields: ["funding_rounds"] returns VALIDATION_FAILED with a pointer to expand.
Semantic search
For "companies doing X", rank startups by meaning instead of keywords:
query ranks by meaning; similar_to: "northvolt.com" finds look-alikes. Use one or the other, without sort. Startups only.
Each row carries _rank (position), _similarity (0–1) and, where calibrated, _match_percent. Read down the list and stop where relevance falls off.
meta.ranking states coverage: within_filter ranks every startup the filter allows; post_filtered means more than 10,000 startups match, so ranking is approximate and strong matches can be missed (narrow the filter to rank within it). Rankings are approximate and never exhaustive: page.total is the size of the ranked list, not of the market.
meta.search_id identifies this exact ranking for 30 minutes. POST /exports {"search_id": "…", "format": "csv"} exports it in the same order, without ranking again.
Jobs: exports and enrichments
Exports and enrichments run in the background as jobs. They share one status vocabulary:
quoting → awaiting_approval → queued → running → succeeded | partially_succeeded | failed
any non-final status → canceling → canceled
Status
Meaning
quoting
working out the price (an enrichment's free VC-backability check runs here)
awaiting_approval
quote is ready; nothing has been charged
queued, running
approved; the quoted maximum is reserved
succeeded
done; read result (exports) or /results (enrichments)
partially_succeeded
done, but some items failed; they carry a message and are not charged
failed
the job could not run; reservations are refunded
canceling → canceled
work already in flight may finish and is settled
Approve:POST /{jobs}/{id}/approve {"quote_id": "…"}. This reserves quote.max_cost_usd_cents, the most you can be charged; only completed work is charged and the rest is refunded. A 0¢ quote starts automatically for API keys.
Quotes expire after 30 minutes but jobs don't. Reading the job issues a fresh quote_id. Approving a stale quote returns 409 QUOTE_EXPIRED with the current quote in error.details.quote. If the price rose, you get 409 PRICE_CHANGED.
Waiting:GET /{jobs}/{id}?wait=10 returns as soon as the status changes, or after 10 seconds. Polling is free; or subscribe to webhooks.
Finding jobs again: set client_reference (your own id, up to 200 characters) on create, and list with GET /exports?client_reference=… or GET /enrichments?client_reference=….
Exports
POST /exports takes the same collection, filter, sort, fields and expand as search, plus format (csv or jsonl). Or send search_id from a semantic search to export that exact ranking. Up to 50,000 rows at 1¢ per 100 rows. Rows are selected when the export runs, usually seconds after approval, and never exceed the quoted row count; a search_id export keeps the ranking's exact membership and order. Expanded relations keep their per-record caps, and each row reports what was cut. When the job succeeds, result.download_url is valid for 5 minutes and renewed on every read; the file is kept for 7 days.
companies: up to 5,000 domains, {"list_id": "…"} or {"csv": "…"} (any website, domain or url column).
Every company first gets a free VC-backability check. check_only: true stops there.
update chooses what to refresh from the web: details (company details), funding and founders. true refreshes data older than 6 months; {"freshness": "12m" | "6m" | "30d" | "always"} sets the age (12m = 365 days, 6m = 183 days, 30d = 30 days). Data newer than that is not refreshed or charged. Without update, you get StartupSeeker's current data for free.
PATCH /enrichments/{id} {"update": …} re-quotes before approval without repeating the check.
GET /enrichments/{id}/results returns one row per company: outcome, the StartupSeeker company record, and per data type whether it was updated, failed or left alone.
Connected AI apps (OAuth) need the enrichment permission granted on the StartupSeeker consent screen; API keys don't.
1¢ per successful request (also when the result is empty)
LinkedIn page read
2¢ per request
Schema, industries, locations, account, docs, job status and results, corrections, webhooks
free
Export
1¢ per 100 rows (unit price 100 micro-USD per row), charged on rows actually written
Enrichment: company details / funding / founders
0.5¢ / 1¢ / 2¢ per company actually updated (5,000 / 10,000 / 20,000 micro-USD)
VC-backability check, StartupSeeker data without updates
free
Charges, balances and caps are whole USD cents. Unit prices are in micro-USD (1,000,000 = $1) because some are fractions of a cent. A job's line total is rounded up to whole cents.
Failed requests are never charged a request fee. Job money is always visible on the job as cost.reserved_usd_cents, charged_usd_cents and refunded_usd_cents.
meta.cost_usd_cents on each response is what that request cost.
Default limits per account (shared by all keys and connected apps; daily limits reset at UTC midnight):
Limit
Default
Rows returned by reads
20,000 per day
Exported rows
50,000 per day
Concurrent heavy queries (search, get, aggregate)
2
Domains entering enrichment
5,000 per day
Concurrent VC checks
3
Enrichment spend
$50 per job, $200 per day
GET /account shows your balance (available and reserved), each limit, today's usage and reset times. Need more? Contact us.
Idempotency and retries
Every POST, PATCH and DELETE that changes something accepts an Idempotency-Key header (1–200 printable characters). Use a new random key per intended change, and the same key when you retry that change.
Same key, same body: the original response is replayed (same status and body, with Idempotent-Replayed: true). Replays are free, use no quota and work even at zero balance.
Same key, different body:409 IDEMPOTENCY_MISMATCH.
Still running:409 IDEMPOTENCY_IN_PROGRESS with Retry-After; retry the identical request.
Failed requests are not stored: fix the request and retry with the same key.
Unknown outcome:500 MUTATION_OUTCOME_UNKNOWN. Retry with the same key, never a new one; the effect happens at most once.
Keys are scoped to your account, method and path, and kept for 24 hours. After that, find jobs again by client_reference.
Search, match and aggregate are POST reads; they don't take keys.
Errors and recovery
{
"error": {
"code": "QUOTE_EXPIRED",
"message": "This quote expired or was replaced. Approve the current quote.",
"param": "quote_id",
"retryable": false,
"doc_url": "https://startup-seeker.com/api-docs/v4#errors-quote-expired",
"details": { "quote": { "quote_id": "…", "max_cost_usd_cents": 120 } }
}
}
code is stable and listed in the error catalog, with one HTTP status per code. param names the field to fix; hint and details (such as did_you_mean, candidates, a new quote, resets_at) carry what you need to recover.
Retry only when retryable is true: wait Retry-After seconds (or back off: 1 s, 2 s, 4 s … up to 30 s) and send the identical request, with the same Idempotency-Key for changes. QUERY_TIMEOUT deserves one retry; if it repeats, narrow the filter.
Don't retry 4xx validation errors unchanged: fix the request.
Every response has an X-Request-Id header; include it when you contact support.
Rate limits
Authenticated responses carry the tightest current window:
Header
Meaning
RateLimit-Limit
requests allowed in the window
RateLimit-Remaining
requests left
RateLimit-Reset
seconds until the window resets
Above the limit you get 429 RATE_LIMITED with Retry-After. Daily row, export and spend quotas return 429 QUOTA_EXCEEDED with details.resets_at; check them any time with GET /account.
Webhooks
Register an HTTPS endpoint and the events it should receive:
data.object is the job as GET returns it, except that download links are left out; GET the job for a fresh link.
Verify the signature
Headers: StartupSeeker-Signature: t=1763200800,v1=5257a8…, plus StartupSeeker-Event-Id and StartupSeeker-Event-Type. v1 is the hex HMAC-SHA256 of "{t}.{raw body}" keyed with your signing secret (the whole string, as UTF-8). Verify the raw body before parsing JSON, compare in constant time, and reject timestamps more than 5 minutes away from now. While a rotated secret is still valid there are two v1 values; accept either.
import crypto from 'node:crypto';
// rawBody: the request body exactly as received (a string or Buffer), before JSON parsing.
export function verifyStartupSeekerSignature(rawBody, header, secret, toleranceSeconds = 300) {
const signatures = [];
let timestamp = null;
for (const part of String(header ?? '').split(',')) {
const [key, value] = part.split('=');
if (key === 't') timestamp = Number(value);
if (key === 'v1') signatures.push(value);
}
if (!Number.isInteger(timestamp) || !signatures.length) return false;
if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest();
return signatures.some(signature => {
const actual = Buffer.from(signature, 'hex');
return actual.length === expected.length && crypto.timingSafeEqual(actual, expected);
});
}
import hashlib, hmac, time
def verify_startupseeker_signature(raw_body: bytes, header: str, secret: str, tolerance_seconds: int = 300) -> bool:
timestamp, signatures = None, []
for part in (header or "").split(","):
key, _, value = part.partition("=")
if key == "t" and value.isdigit():
timestamp = int(value)
elif key == "v1":
signatures.append(value)
if timestamp is None or not signatures or abs(time.time() - timestamp) > tolerance_seconds:
return False
expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(expected, signature) for signature in signatures)
Delivery
Answer with any 2xx within 15 seconds. Otherwise the delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and then daily, for about 3 days. Each attempt is signed again with a fresh t; the event id and body stay the same.
Deliveries can repeat or arrive out of order: deduplicate by id, and read the job for its current state.
GET /webhooks/{id}/deliveries shows the last 30 days (status, attempts, last response). POST /webhooks/{id}/deliveries/{delivery_id}/redeliver sends one again.
POST /webhooks/{id}/rotate_secret issues a new secret; the old one keeps signing alongside it for 24 hours.
Corrections have no events; use GET /corrections/{id}?wait=10.
Data model and consistency
Merges: duplicate records are merged; old refs resolve to the survivor, which has merged_from. Store id, not the domain.
Removed records: a suppressed or deleted record returns 404. Remove it on your side.
Unknown versus zero:null is unknown. A missing total_funding_usd is not zero, and a company without rounds may still have a funding total.
Freshness:refreshed_at is when our serving copy was rebuilt. It does not mean a value changed.
Funding: totals, rounds and investor links are independent measures; a total can exist without accepted rounds. Only accepted, non-superseded rounds and exits are returned.
Pages are live; exports are a single consistent read taken when the export runs (a search_id export keeps its ranking's membership and order).
Sources:expand: ["sources"] shows evidence for specific fields. Treat unsourced fields as StartupSeeker's best current value.
Using with AI agents
MCP: connect Claude, ChatGPT or Cursor to https://startup-seeker.com/mcp/v4 and sign in with OAuth (setup). The MCP tools use the same data, filters (this object form or the predicate form), quotas and balance as the REST API, and return compact CSV with a summary line. Paid steps return a quote that the person approves.
For your own agent over REST: give it /api/v4/docs.md (this guide plus an endpoint index, small enough for a context window), the per-endpoint pages linked from it, and OpenAPI.
Good behaviour: report meta.applied_filter when you narrow a question; say when a total is exact: false or a page was shortened; treat null as unknown; never present a semantic ranking or truncated relation as complete; ask before approving a quote above 0¢.
Versioning and changelog
The version is in the path (/api/v4). Within v4 we only add things: new endpoints, new optional parameters, new response fields and new error codes. Build clients that ignore unknown fields.
Breaking changes get a new major version and at least 3 months of overlap. Retiring versions answer with Deprecation and Sunset headers.
v3 (/api/v3) is deprecated as of v4's release; it keeps working for at least 3 months after v4 general availability. v2 ends on 2026-12-31.
Changelog
2026-11-15: v4.0.0. First release of v4: object filter grammar, cursor-only pagination with pages that fit, nested expand pages, /match, named aggregate columns, one job lifecycle with approval and ?wait, client_reference, free idempotent replays, a typed error catalog, rate-limit headers, /account, and signed webhooks with subscriptions, rotation and a delivery log.
Migrate from v3
v3
v4
POST /{collection}/search with a predicate tree
same path; filter is an object: {"field":"hq_country","op":"eq","value":"DE"} → {"hq_country":"DE"}
Up to 100 domains, UUIDs, LinkedIn URLs or names in one call. One result per input, in input order: exact, candidates, not_found or invalid. Names never become exact.
Exact counts and metrics, optionally grouped by up to two fields (dates by year, quarter or month). Columns carry real names; the top 100 groups are returned.
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.
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
Up to three field names; prefix "-" for descending. NULL sorts last; id breaks ties.
fields
array
Fields to return. Omit for the default fields. id is always returned.
expand
array
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
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).
Get a record (get). One record by UUID, domain, slug or LinkedIn URL (funding rounds and exits: UUID). expand nests related records with their own pagination.
1¢ per successful request. API key required. Success: 200.
UUID, domain, slug or LinkedIn URL (percent-encode URLs).
Query parameters
Name
Type
Required
Description
fields
array (comma-separated)
expand
array (comma-separated)
Response
Name
Type
Required
Description
data
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.
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.
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.
401
UNAUTHORIZED
The API key is missing, invalid or revoked.
402
INSUFFICIENT_FUNDS
The account balance cannot cover this request or job.
404
NOT_FOUND
The record or resource does not exist for this account.
409
REF_AMBIGUOUS
The ref matches several records.
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
curl -X GET 'https://startup-seeker.com/api/v4/startups/stripe.com?fields=name,domain,total_funding_usd&expand=funding_rounds' \
-H "Authorization: Bearer $STARTUPSEEKER_API_KEY"
GET /api/v4/{collection}/{id}/{relation}
List related records (relation). Page through one relation of a record (e.g. a startup's funding_rounds or an investor's portfolio) by the parent's UUID.
1¢ per successful request. API key required. Success: 200.
A to-many relation listed under expand in /schema.
Query parameters
Name
Type
Required
Description
fields
array (comma-separated)
limit
integer
cursor
string
Response
Name
Type
Required
Description
data
array
yes
The results.
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.
Errors
Status
Code
Meaning
400
VALIDATION_FAILED
The request does not match the endpoint contract.
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.
404
NOT_FOUND
The record or resource does not exist for this account.
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
curl -X GET 'https://startup-seeker.com/api/v4/investors/11111111-1111-4111-8111-111111111111/portfolio?limit=50' \
-H "Authorization: Bearer $STARTUPSEEKER_API_KEY"
POST /api/v4/{collection}/match
Match refs and names (match). Up to 100 domains, UUIDs, LinkedIn URLs or names in one call. One result per input, in input order: exact, candidates, not_found or invalid. Names never become exact.
1¢ per successful request. API key required. Success: 200.
Count and summarise (aggregate). Exact counts and metrics, optionally grouped by up to two fields (dates by year, quarter or month). Columns carry real names; the top 100 groups are returned.
1¢ per successful request. API key required. Success: 200.
Schema (schema). Fields, types, filter operators, sortable and groupable fields and expandable relations for every collection. Free and public; cache for an hour.
Free. Public. Success: 200.
Response
Name
Type
Required
Description
data
object
yes
The result.
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.
Errors
Status
Code
Meaning
400
VALIDATION_FAILED
The request does not match the endpoint contract.
500
INTERNAL_ERROR
An unexpected server error.
503
SERVICE_UNAVAILABLE
A dependency is temporarily unavailable.
Example
curl -X GET 'https://startup-seeker.com/api/v4/schema'
GET /api/v4/schema/{collection}
Schema for one collection (schema_collection). The schema of one collection; add ?fields=a,b for just those fields.
Create an export (create_export). Quote a CSV or JSONL file of a search (or of a semantic search by search_id). The job waits for approval; a 0¢ quote starts at once.
Free. API key required. Success: 202. Accepts Idempotency-Key.
Create an enrichment (create_enrichment). Check up to 5,000 companies (free VC-backability check), then quote web updates of company details, funding or founders. A 0¢ quote starts on its own.
Free. API key required. Success: 202. Accepts Idempotency-Key.
Body
Name
Type
Required
Description
companies
array | object
yes
Domains (≤5,000), {"list_id": …} or {"csv": "…"} with a website/domain/url column.
companies.list_id
string
yes
check_only
boolean
Run only the free VC-backability check. The job succeeds after the check and has no quote.
update
object
Which data to refresh from the web. true = refresh data older than 6 months; {"freshness":"12m"|"6m"|"30d"|"always"}; false or omitted = keep StartupSeeker data.
update.details
boolean | object
update.funding
boolean | object
update.founders
boolean | object
client_reference
string
Your own reference (≤200 chars). Filter job lists by it to find work again.
The record or resource does not exist for this account.
429
RATE_LIMITED
Too many requests in the current window.
500
INTERNAL_ERROR
An unexpected server error.
503
SERVICE_UNAVAILABLE
A dependency is temporarily unavailable.
Example
curl -X GET 'https://startup-seeker.com/api/v4/enrichments/<id>' \
-H "Authorization: Bearer $STARTUPSEEKER_API_KEY"
PATCH /api/v4/enrichments/{id}
Change what to update (configure_enrichment). Change update before approval. Returns a new quote without re-running the check.
Free. API key required. Success: 200. Accepts Idempotency-Key.
Path parameters
Name
Type
Required
Description
id
string
yes
Enrichment UUID.
Body
Name
Type
Required
Description
update
object
yes
Which data to refresh from the web. true = refresh data older than 6 months; {"freshness":"12m"|"6m"|"30d"|"always"}; false or omitted = keep StartupSeeker data.
Approve an enrichment (approve_enrichment). Start the updates at the quoted price. Reserves quote.max_cost_usd_cents; only updates that succeed are charged.
Free. API key required. Success: 200. Accepts Idempotency-Key.
Path parameters
Name
Type
Required
Description
id
string
yes
Enrichment UUID.
Body
Name
Type
Required
Description
quote_id
string
yes
The quote_id you are approving. A stale id returns 409 QUOTE_EXPIRED with the new quote.
Every error has this shape: {"error": {"code", "message", "param"?, "hint"?, "retryable", "doc_url", "details"?}}. One HTTP status per code.
Status
Code
Meaning
What to do
Retry
400
COLUMN_NAME_CONFLICT
Two aggregate columns would have the same name.
Give one of the metrics an explicit as name.
no
400
CURSOR_INVALID
The cursor is malformed, belongs to another query or another account.
Send the cursor exactly as returned, with the same API key, or start again without a cursor.
no
400
OPERATOR_NOT_SUPPORTED
The operator is not available for this field.
Use one of the operators listed for the field in /schema.
no
400
QUERY_TOO_COMPLEX
The filter exceeds the complexity limits.
Stay within 3 nesting levels, 30 predicates and 100 values per array.
no
400
SEMANTIC_NOT_SUPPORTED
Semantic ranking (query / similar_to) is only available for startups.
Use a text match filter on other collections.
no
400
TAG_ARRAY_NEEDS_OPERATOR
A bare array was given for a tag field.
Say whether any or all values must match: {"any": [...]} or {"all": [...]}.
no
400
UNKNOWN_FIELD
A field name is not part of this collection.
Use a name from GET /schema/{collection}; details.did_you_mean lists close matches.
no
400
VALIDATION_FAILED
The request does not match the endpoint contract.
Correct the field named in param using hint.
no
400
VALUE_AMBIGUOUS
A friendly filter value matches several canonical values.
Pick one of details.candidates.
no
400
VALUE_UNKNOWN
A filter value does not match any known value.
Use a canonical value; details.did_you_mean lists close matches.
no
401
UNAUTHORIZED
The API key is missing, invalid or revoked.
Send Authorization: Bearer ssk_live_… with an active key from /account/api-keys.
no
402
INSUFFICIENT_FUNDS
The account balance cannot cover this request or job.
Top up the balance, then retry.
no
403
FORBIDDEN
This key or application may not perform the operation.
For OAuth apps, grant the permission on the StartupSeeker consent screen.
no
403
SPEND_LIMIT_EXCEEDED
A per-job or daily enrichment spend limit would be exceeded.
Reduce the job or wait until details.resets_at.
no
404
NOT_FOUND
The record or resource does not exist for this account.
Check the id or ref; resources are account-scoped.
no
404
RECORD_REMOVED
The record was suppressed or deleted.
Remove the ref from your system.
no
405
METHOD_NOT_ALLOWED
The endpoint exists but not with this HTTP method.
Use a method listed in the Allow header.
no
409
CHECK_ONLY_JOB
A check-only enrichment has nothing to approve or configure.
Read its results, or create a job without check_only.
no
409
CONFLICT
The resource changed concurrently or already exists.
Read the resource and retry the change.
no
409
IDEMPOTENCY_IN_PROGRESS
A request with this Idempotency-Key is still running.
Retry the identical request with the same key after Retry-After.
yes
409
IDEMPOTENCY_MISMATCH
This Idempotency-Key was already used with a different request.
Use a new key for a different request.
no
409
JOB_NOT_CONFIGURABLE
The job can no longer be reconfigured.
Only jobs awaiting approval can change; create a new job instead.
no
409
PRICE_CHANGED
The price rose since the quote was issued.
Review details.quote and approve its quote_id.
no
409
QUOTE_EXPIRED
The quote is older than 30 minutes or was replaced.
Approve the new quote in details.quote (or read the job for it).
no
409
QUOTE_NOT_READY
The job is still quoting.
Wait for status awaiting_approval (GET with ?wait=10).
yes
409
REF_AMBIGUOUS
The ref matches several records.
Use one of the UUIDs in details.candidates.
no
410
CURSOR_EXPIRED
The cursor expired (24 h, or 30 min for semantic rankings).
Run the query again without a cursor.
no
410
SEARCH_EXPIRED
The ranked search (search_id) expired after 30 minutes.
Run the semantic search again and use its new search_id.
no
413
BODY_TOO_LARGE
The request body exceeds 16 KB.
Send fewer values; split large inputs across requests.
no
413
RECORD_TOO_LARGE
A single record exceeds the 1 MB response budget.
Request fewer fields or expands.
no
429
QUOTA_EXCEEDED
A daily or concurrency quota is used up.
Wait until details.resets_at; see GET /account.
yes
429
RATE_LIMITED
Too many requests in the current window.
Wait for Retry-After seconds.
yes
500
INTERNAL_ERROR
An unexpected server error.
Retry once; contact support with the request id if it persists.
yes
500
MUTATION_OUTCOME_UNKNOWN
The change may or may not have been applied.
Retry with the same Idempotency-Key; never with a new key. Read the resource to reconcile.
yes
503
SERVICE_UNAVAILABLE
A dependency is temporarily unavailable.
Retry after Retry-After seconds.
yes
504
QUERY_TIMEOUT
The query ran out of its time budget.
Retry once; if it repeats, narrow the filter.
yes
Fields: startups
Field
Type
Filter
Sort
Group
Default
Meaning
id
ref
in, nin
yes
yes
yes
Stable canonical entity UUID.
slug
text
eq, in, prefix, match
yes
yes
yes
Domain alias when available; UUID for domainless entities.
name
text
eq, in, prefix, match
yes
yes
yes
Public display name.
domain
text
eq, in, prefix, match
yes
yes
yes
Canonical domain, nullable for investors.
linkedin_url
text
eq, in, prefix, match
yes
yes
Public LinkedIn company URL.
hq_country
enum
eq, ne, in, nin, exists
yes
yes
yes
Headquarters country ISO 3166-1 alpha-2.
hq_admin1
text
eq, in, prefix, match
yes
yes
Headquarters country-qualified administrative area code.
hq_city
text
eq, in, prefix, match
yes
yes
Headquarters GeoNames city identifier.
hq_region
tags
any, all, none, empty
yes
Country-level geographic region slugs of the headquarters; overlapping groups such as Europe and EMEA are returned together. Values: north_america, south_america, central_america, caribbean, latam, europe, european_union, asia, middle_east, mena, africa, oceania, south_asia, se_asia, greater_china, uk_ireland, dach, nordics, benelux, baltics, americas, apac, emea.
founded_year
integer
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
Year founded.
employees
integer
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
Latest evidenced employee count.
linkedin_followers
integer
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
Latest LinkedIn follower count.
refreshed_at
datetime
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
Time the serving projection was refreshed; does not imply returned data changed.
description
text
eq, in, prefix, match
yes
yes
yes
Short startup description.
status
enum
eq, ne, in, nin, exists
yes
yes
yes
Current lifecycle status. Values: active, inactive, acquired, shut_down, unknown.
industries
tags
any, all, none, empty
yes
yes
Canonical industry taxonomy slugs.
locations
relation
in, nin
Any evidenced office location; ISO2 country, admin1 code, region slug or GeoNames city ID.
score
number
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
yes
Startup traction score.
total_funding_usd
money (USD)
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
yes
Effective lifetime funding total using human-lock and lifetime-total precedence.
Linked investor at startup level or in any accepted round.
funding_rounds
relation
some
Any effective accepted funding round.
lists
relation
in, nin
Owned saved list membership.
added_at
datetime
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
Canonical entity creation time.
Expand:funding_rounds (up to 20 per record), investors (up to 25 per record), founders (up to 10 per record), locations (up to 25 per record), sources (up to 5 per record).
Fields: investors
Field
Type
Filter
Sort
Group
Default
Meaning
id
ref
in, nin
yes
yes
yes
Stable canonical entity UUID.
slug
text
eq, in, prefix, match
yes
yes
yes
Domain alias when available; UUID for domainless entities.
name
text
eq, in, prefix, match
yes
yes
yes
Public display name.
domain
text
eq, in, prefix, match
yes
yes
yes
Canonical domain, nullable for investors.
linkedin_url
text
eq, in, prefix, match
yes
yes
Public LinkedIn company URL.
hq_country
enum
eq, ne, in, nin, exists
yes
yes
yes
Headquarters country ISO 3166-1 alpha-2.
hq_admin1
text
eq, in, prefix, match
yes
yes
Headquarters country-qualified administrative area code.
hq_city
text
eq, in, prefix, match
yes
yes
Headquarters GeoNames city identifier.
hq_region
tags
any, all, none, empty
yes
Country-level geographic region slugs of the headquarters; overlapping groups such as Europe and EMEA are returned together. Values: north_america, south_america, central_america, caribbean, latam, europe, european_union, asia, middle_east, mena, africa, oceania, south_asia, se_asia, greater_china, uk_ireland, dach, nordics, benelux, baltics, americas, apac, emea.
founded_year
integer
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
Year founded.
employees
integer
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
Latest evidenced employee count.
linkedin_followers
integer
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
Latest LinkedIn follower count.
refreshed_at
datetime
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
Time the serving projection was refreshed; does not imply returned data changed.
organization_types
tags
any, all, none, empty
yes
Canonical investor organization types.
aum_usd
money (USD)
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
Estimated assets under management.
check_size_min_usd
money (USD)
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
min recorded firm-level investment check size in USD. Legacy zero/nonpositive values are unknown (null), never a confirmed bound. Positive recorded bounds are not independent source verification and do not prove a specific strategy accepts the amount.
check_size_typ_usd
money (USD)
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
typ recorded firm-level investment check size in USD. Legacy zero/nonpositive values are unknown (null), never a confirmed bound. Positive recorded bounds are not independent source verification and do not prove a specific strategy accepts the amount.
check_size_max_usd
money (USD)
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
max recorded firm-level investment check size in USD. Legacy zero/nonpositive values are unknown (null), never a confirmed bound. Positive recorded bounds are not independent source verification and do not prove a specific strategy accepts the amount.
stages
tags
any, all, none, empty
yes
Firm-wide investment stage keys, trimmed and case-insensitive; unfamiliar labels are preserved. A stage and industry may belong to different funds or strategies; inspect investment_thesis before asserting joint fit.
geo_scope
tags
any, all, none, empty
yes
Geographic investment scope.
target_industries
tags
any, all, none, empty
yes
Firm-wide target industry taxonomy slugs; independent of stage tags, not proof that one strategy targets both.
investment_thesis
text
eq, in, prefix, match
yes
yes
Public investment thesis. Use explicit stage/sector/strategy linkage; split strategies and omissions cannot establish a joint fit from firm tags alone.
portfolio_claimed_count
integer
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
yes
Distinct companies claimed in portfolio sources, including unresolved companies.
portfolio_linked_count
integer
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
yes
Distinct linked startup entities in portfolio.
average_portfolio_score
number
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
Average score of linked portfolio companies.
portfolio_quality_score
number
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
yes
UI portfolio quality score.
top_industries
text
eq, in, prefix, match
yes
yes
yes
Most common industries among linked portfolio companies with their share of companies whose industry is known, e.g. "cleantech 62%|energy 31%". Observed portfolio mix, not a stated mandate. For sector specialists rank with search focus.
lead_preference
enum
eq, ne, in, nin, exists
yes
yes
Preference for leading investments.
last_deal_at
date
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
Latest accepted funding round participation.
deals_last_12m
integer
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
Distinct accepted rounds participated in during the trailing 12 months.
Distinct accepted rounds matching where and optional lead/participant role.
Expand:partners (up to 10 per record), portfolio (up to 25 per record), funds (up to 20 per record), co_investors (up to 25 per record), deal_stats (one record), sources (up to 5 per record).
Headquarters country-qualified administrative area code.
hq_city
text
eq, in, prefix, match
yes
yes
Headquarters GeoNames city identifier.
hq_region
tags
any, all, none, empty
yes
Country-level geographic region slugs of the headquarters; overlapping groups such as Europe and EMEA are returned together. Values: north_america, south_america, central_america, caribbean, latam, europe, european_union, asia, middle_east, mena, africa, oceania, south_asia, se_asia, greater_china, uk_ireland, dach, nordics, benelux, baltics, americas, apac, emea.
industries
tags
any, all, none, empty
yes
Startup industry taxonomy slugs.
investors
relation
in, nin, role
Linked accepted round investor role edges.
startup
relation
some
Filter the linked startup.
Expand:investors (up to 25 per record), startup (one record), sources (up to 5 per record).
Fields: exits
Field
Type
Filter
Sort
Group
Default
Meaning
id
ref
in, nin
yes
yes
yes
Stable accepted exit event UUID.
startup_id
ref
in, nin
yes
yes
yes
Canonical startup entity UUID.
exit_type
enum
eq, ne, in, nin, exists
yes
yes
yes
Acquisition or IPO. Values: acquisition, ipo.
event_date
date
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
yes
Accepted exit event date.
price_usd
money (USD)
eq, in, ne, gt, gte, lt, lte, between, exists
yes
yes
Disclosed acquisition or IPO price in USD.
acquirer_id
ref
in, nin
yes
yes
Resolved acquirer canonical entity UUID.
acquirer_name
text
eq, in, prefix, match
yes
yes
Acquirer display name.
acquirer_domain
text
eq, in, prefix, match
yes
yes
Acquirer domain.
hq_country
enum
eq, ne, in, nin, exists
yes
yes
yes
Headquarters country ISO 3166-1 alpha-2.
hq_admin1
text
eq, in, prefix, match
yes
yes
Headquarters country-qualified administrative area code.
hq_city
text
eq, in, prefix, match
yes
yes
Headquarters GeoNames city identifier.
hq_region
tags
any, all, none, empty
yes
Country-level geographic region slugs of the headquarters; overlapping groups such as Europe and EMEA are returned together. Values: north_america, south_america, central_america, caribbean, latam, europe, european_union, asia, middle_east, mena, africa, oceania, south_asia, se_asia, greater_china, uk_ireland, dach, nordics, benelux, baltics, americas, apac, emea.
industries
tags
any, all, none, empty
yes
Startup industry taxonomy slugs.
startup
relation
some
Filter the linked startup.
acquirer
relation
in, nin
Acquirer UUID, domain or exact name.
Expand:startup (one record), acquirer (one record), sources (up to 5 per record).