For coding agents

Base URL:  https://api.sproutsdata.ai
Header:    X-API-Key: $SPROUTS_API_KEY        (sk_dsp_live_... or sk_dsp_test_...)
Requests:  Content-Type: application/json     (unknown body fields => 422)
Errors:    application/problem+json           (switch on `code`, never on text)
Rule:      keys are SERVER-SIDE ONLY — Origin header + X-API-Key => 403 auth.browser_origin
Rule:      a key goes in X-API-Key ONLY. `Authorization: Bearer` is for OAuth delegation tokens;
           an sk_dsp_ key sent as Bearer => 401 auth.unauthorized (the MCP server is the exception:
           it accepts a key as Bearer and forwards it as X-API-Key)

Basic search  (mode fast)   0.5   for the first 10 results, then 0.08 per extra result
AI search     (mode auto)   0.595 for the first 10 results, then 0.085 per extra result
Similar / relationships / reach / ask   2 for the first 10 results, then 1 per next 10 (part blocks count as full)
Ask routed to shared institutions, /relationships/institutions   2 flat
Record lookup (/v1/entities/*)          1 per record FOUND; found:false ids are free
Org chart (/v1/org-chart, …)            1 flat; an org chart call that finds nothing is free
Agent run by effort   minimal 1.02 · low 2.125 · medium 8.5 · high 42.5 · xhigh 85 — charged only if the run SUCCEEDS
                      auto holds 85, then is charged the effort it ran (today: high, 42.5)
Deep search (mode deep)                 the agent price of the effort it ran (today: minimal, 1.02), even with no rows
Free                                    coverage, credits, usage, history, filters, sorts, run reads, feedback, votes, lists, members, top-up routes

{
  "query": "fintech companies in berlin",   // optional IF filters given; at least one required
  "mode": "fast",                            // fast (no LLM) | auto (LLM infers filters) | deep (company/person only; one page, no cursor; filters, domains and sort not applied yet)
  "category": "company",                     // default company
  "filters": {                               // shapes vary per category; unknown keys => 422
    "industry": {"include": ["Software & Technology"]},          // TermsFilter
    "employee_count": {"gte": 500, "lte": 5000},                 // RangeFilter
    "last_funding_date": {"period": {"gte": "2024-01-01"}}       // DateFilter — bounds MUST nest under "period"
  },                                         // person: "tenure" = years in the CURRENT role; "years_worked" = whole
                                             // years across every job held ({"lte": 3} = early career; {"gte": N} =
                                             // some job started at least N years ago)
  "include_domains": ["adyen.com"],          // company/person/job_opening ONLY; max 100
  "exclude_domains": [],
  "sort": [{"field": "employee_count", "direction": "desc"}],  // <=3 clauses, strongest first; direction defaults "desc"
                                             // needs an explicit `category`; duplicate field => 422
                                             // vocabulary: GET /v1/sorts/{category} — NEVER hard-code it
  "limit": 10,                               // 1..100, default 10 (what a search's base price covers)
  "cursor": null                             // from previous next_cursor
}

{
  "query": "who at Adyen do we know from Stripe",  // 1..2000 chars; the only required field
  "limit": 10,                                      // 1..100, default 10
  "cursor": null                                    // carries the plan — paging never re-reads the sentence
}
// Response: {"route": "relationships"|"reach"|"institutions"|"compare"|"fan_out",
//            "reading": {"span", "searches", "warnings": []},
//            + EXACTLY ONE of relationships|reach|institutions|compare|fan_out}
// READ `route` FIRST. The five shapes are different answers, not variants of one.
// `compare` and `fan_out` are never paginated: next_cursor null means "no pages", not "last page".
// An ambiguous question is REFUSED (422), never guessed at. A name matching two companies is
// 422 relationship.anchor_ambiguous with extra.anchor + extra.candidates.

{
  "anchors": [                               // 1..10
    {"value": "adyen.com", "by": "domain", "weight": 1.0}   // by: domain | li_url | name (no id)
  ],
  "combine": "and",                          // and = like ALL together; or = like ANY one
  "category": "company",                     // anything else => 422
  "limit": 10,                               // default 10: one block of the look-alike price
  "cursor": null
}

{
  "ids": ["adyen.com", "checkout.com"],      // without `by`: internal ids
  "by": "domain",                            // auto | domain | li_url | name; persons: no domain
  "fields": ["account_name", "industry"]     // omit for full record
}

// Header: Idempotency-Key: <one new value per intended run, ≤ 255 chars>   REQUIRED
{
  "query": "series B fintechs in Germany that sell to banks",  // 1..4000 chars; the only required field
  "category": "company",          // company | person; default company
  "effort": "medium",             // minimal | low | medium (default) | high | xhigh | auto
  "criteria": ["sells to banks"], // ≤ 10 prose checks applied to every row
  "enrichments": ["cto_name"],    // ≤ 20 column names; listed in `columns`, value keyed by name on each row
  "exclusion": ["adyen.com"]      // ≤ 1,000 entity ids to leave out
}
// Unknown fields => 422. 202 {run_id, status, meta}; a reused Idempotency-Key => 200 + the ORIGINAL run.
// Statuses: pending | running | completed | failed | cancelled.

{
  "results": [ /* hits: {id, category, score, ...record fields flattened} — entities: EntityHit below */ ],
  "total": 10000,              // match count
  "total_is_estimate": true,   // true => total is a FLOOR ("10000+"), never render as exact
  "has_more": true,            // invariant: has_more == (next_cursor != null)
  "next_cursor": "eyJ...",     // opaque + signed; pass back as `cursor`
  "resolved_search": {         // how the query was interpreted (null on entities)
    "parser_version": "none",  // "none" when no LLM ran (fast, similar, cursor pages)
    "mode": "fast", "category": "company", "query": "...",
    "filters": {},             // the EFFECTIVE filters searched
    "filters_source": "none",  // caller | parser | caller+parser | none
    "semantic_query": null, "sort": null, "conflicts": [], "overrides": []
  },
  "suggestion": null,          // or {"kind": "search"|"agentic", "category": …|null, "message": "…"}
                               // ADVISORY: the search asked for is the one that ran. `agentic` => POST /v1/agents/runs
                               // (a paid, multi-step run: see "POST /v1/agents/runs" above)
  "coverage": null,            // null = NOT MEASURED (fast/auto never enumerate), never "zero coverage".
                               // When set: {universe, universe_is_exact, enumerated, enumeration_recall,
                               //            universe_exhausted, truncated_by, constraints_unmet[]}
                               // enumeration_recall is null unless the universe was exact, and it measures
                               // the RESOLVED query, not your intent.
  "attribution": [             // source, not citation; url/quote RESERVED, always null in v1
    {"source_corpus": "gtm_index", "domain": null, "as_of": "2026-08-12T19:52:31Z", "url": null, "quote": null}
  ],
  "degradation": [             // [] means "checked, nothing degraded" — NEVER "unknown"
    {"reason": "vector_coverage_incomplete", "detail": "...", "impact": "recall", "source_corpus": "gtm_index"}
  ],
  "columns": null,             // or [{name, description, source}] when a run carries extra columns;
                               // each column's value sits on every row keyed by `name`. null = plain entity table.
  "meta": {
    "request_id": "fc8735204043c339af9e9cbffaff2b21",  // also X-Request-Id header; always log
    "environment": "live",     // or "test"
    "as_of": "2026-08-12T19:52:31Z",
    "credential": "api_key",   // or "session" (dashboard playground)
    "credits_charged": 0.5     // what THIS request cost, to at most 3 decimals. 0 = it cost nothing: a search that found
                               // nothing, rows already paid for (a cursor sent again, or the same Idempotency-Key on the
                               // same UTC day), or a test key. null on a free route
  }
}

{"id": "adyen.com", "category": "company", "found": true,
 "matches": [ /* records; typed for companies/persons */ ]}
// `matches` is ALWAYS A LIST and [] on a miss. An id lookup resolves to exactly one, so matches[0]
// is the record; `by: "name"` can resolve to several, and reading matches[0] there drops the rest.
// Misses come back found:false — NEVER omitted. You are billed 1 credit per record FOUND; misses are free.
// Entities responses never paginate: has_more false, next_cursor null, total exact, resolved_search null.

// GET /v1/coverage
{"segments": [{"name": "...", "category": "company", "total": 43605942, "with_embeddings": 13000000,
               "with_domain": null, "freshest": null, "stalest": null}],
 "not_in_index": ["private companies with no web or LinkedIn presence"],
 "as_of": "...", "degradation": [], "meta": {}}
// with_embeddings null = not measured; 0 = no vectors. People are 0 today (no semantic ranking for people).
// The `affiliations` segment counts employment/education EDGES (about five per person), not people, and
// is filed under category "person": skip it when summing person totals.
// freshest/stalest are always null today. Reference: https://dashboard.sproutsdata.ai/docs/api-reference/coverage

// GET /v1/credits — spendable is the ONLY number that predicts a charge; never add allocated+shared
{"platform": "dsp", "scope": "platform",
 "allocated": {"granted": 1000, "remaining": 993.3, "reserved": 0, "expires_at": "..."},
 "shared": {"remaining": 624},   // reported, NOT spendable on this platform
 "spendable": 993.3, "as_of": "...", "meta": {}}   // credit figures are numbers to 3 decimals
// scope "tenant_wide_fallback": allocated/shared null, only spendable meaningful

// GET /v1/keys/usage
{"key_id": "ak_...", "period_from": "...", "period_to": "...", "granularity": "day",
 "total_requests": 412, "total_credits": 268.415,
 "buckets": [{"period_start": "...", "action_type": "dsp.search.fast", "requests": 31, "credits": 15.5}],
 "meta": {}}

{"type": "https://dashboard.sproutsdata.ai/errors/credits-insufficient", "title": "Insufficient credits",
 "status": 402, "code": "credits.insufficient", "detail": "This action costs 0.595 credits; 0.25 available.",
 "instance": "/v1/search", "request_id": "bd22794d0c5c06f1d3e7045e3c0e32ab",
 "extra": {"available": 0.25, "required": 0.595, "action_type": "dsp.search.auto"}}

# 1. Natural-language company search
curl -X POST https://api.sproutsdata.ai/v1/search \
  -H "X-API-Key: $SPROUTS_API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "industrial automation companies in Germany", "mode": "auto", "category": "company", "limit": 10}'

# 2. Pure filter search (no LLM, exact total)
curl -X POST https://api.sproutsdata.ai/v1/search \
  -H "X-API-Key: $SPROUTS_API_KEY" -H "Content-Type: application/json" \
  -d '{"category": "company", "filters": {"industry": {"include": ["Software & Technology"]}, "employee_count": {"gte": 500, "lte": 5000}}, "limit": 10}'

# 3. Page 2 — same body + cursor from page 1's next_cursor
curl -X POST https://api.sproutsdata.ai/v1/search \
  -H "X-API-Key: $SPROUTS_API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "industrial automation companies in Germany", "mode": "auto", "category": "company", "limit": 10, "cursor": "eyJmIjoiMDNjMjUzNzk3MjM3MTI3ZSIsIm8iOjEs..."}'

# 4. Look-alike companies from two anchors
curl -X POST https://api.sproutsdata.ai/v1/similar \
  -H "X-API-Key: $SPROUTS_API_KEY" -H "Content-Type: application/json" \
  -d '{"anchors": [{"value": "adyen.com", "by": "domain"}, {"value": "checkout.com", "by": "domain"}], "combine": "and", "limit": 10}'

# 5. Full company records by domain
curl -X POST https://api.sproutsdata.ai/v1/entities/companies \
  -H "X-API-Key: $SPROUTS_API_KEY" -H "Content-Type: application/json" \
  -d '{"ids": ["adyen.com", "checkout.com"], "by": "domain", "fields": ["account_name", "industry", "employee_count"]}'

# 6. Explicit ordering (needs an explicit category)
curl -X POST https://api.sproutsdata.ai/v1/search \
  -H "X-API-Key: $SPROUTS_API_KEY" -H "Content-Type: application/json" \
  -d '{"category": "company", "filters": {"industry": {"include": ["Software & Technology"]}}, "sort": [{"field": "employee_count", "direction": "desc"}], "limit": 10}'

# 7. A relationship question in words — the server picks the route
curl -X POST https://api.sproutsdata.ai/v1/relationships/ask \
  -H "X-API-Key: $SPROUTS_API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "who at Adyen do we know from Stripe", "limit": 10}'

# 8. One company's people by department and seniority
curl -X POST https://api.sproutsdata.ai/v1/org-chart \
  -H "X-API-Key: $SPROUTS_API_KEY" -H "Content-Type: application/json" \
  -d '{"domain": "adyen.com"}'

# 9. Vocabulary, balance and coverage (all free)
curl https://api.sproutsdata.ai/v1/sorts/company -H "X-API-Key: $SPROUTS_API_KEY"
curl "https://api.sproutsdata.ai/v1/search/filters/industry?level=parents" -H "X-API-Key: $SPROUTS_API_KEY"
curl https://api.sproutsdata.ai/v1/credits -H "X-API-Key: $SPROUTS_API_KEY"
curl https://api.sproutsdata.ai/v1/coverage -H "X-API-Key: $SPROUTS_API_KEY"