Endpoints

Document records

Fetch full patents, news articles, trends, market reports, funding rounds, academic reports and job openings by id, or four of them by name.

POST/v1/entities/patents

Look up patents by id

Scope: dsp.entities.read

Use it when you know which documents you want and need their full records: a patent by its number, a trend by its name, a funding round by the company it belongs to. Outcome: one result per value you sent, in order, with the records under matches and misses reported as found: false. Worked use cases: Record Lookup guide.

Seven routes, one per document category. They share one request shape, one response shape and one price, and differ in what ids can be:

Routeids areby
/v1/entities/patents (this one)Patent numbersNot accepted
/v1/entities/trendsTrend namesNot accepted
/v1/entities/academic-reportsDOIsNot accepted
/v1/entities/newsHeadlines, or internal idsname (default) or id
/v1/entities/market-reportsReport titles, or internal idsname (default) or id
/v1/entities/fundingsThe company a round belongs to, or internal idsname (default) or id
/v1/entities/job-openingsJob roles, or internal idsname (default) or id

All seven need dsp.entities.read.

What the seven routes share#

Request

FieldNotes
idsRequired. 1 to 100 values per request, or 1 to 50 when by is name
fieldsOptional list of field names. Omit it for the full record, including the large fields (full article bodies, patent publication detail, a trend's list of startups)
byOnly on news, market-reports, fundings and job-openings. See below

Unknown fields are a 422, so sending by to patents, trends or academic-reports is refused rather than ignored. Going over a cap is also a 422, and nothing is charged.

The id on a search hit is not an internal id (for a document it is an opaque hash), so it does not resolve with "by": "id" either. Look a document up by its own identifier: the patent number, trend name, DOI, headline, title, company or role.

Idempotency-Key is optional. Send it when you might retry: the same key, on the same request, from the same credential, on the same UTC day is not charged again for records already paid for. See Retries.

Response

Each results[] row is an EntityHit: the echoed input (id), whether it resolved (found), and the records under matches, restricted to your fields when you sent them.

  • An id lookup (patents, trends, academic-reports, or "by": "id") puts exactly one record in matches, or none for a miss.
  • A name lookup ("by": "name") keeps every candidate, so matches can hold several records: a company can have several funding rounds, and a role can have many open postings. Job openings come back most recent first; the other three are ordered by how well they match.

Rows come back in the order sent, duplicates included, and a value that finds nothing comes back with found: false and an empty matches.

Patents#

The ids are patent numbers.

curl -X POST "https://api.sproutsdata.ai/v1/entities/patents" \
  -H "X-API-Key: $SPROUTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "ids": [
         "US1234567B2"
       ],
       "fields": [
         "patent_id",
         "title",
         "status",
         "granted_date"
       ]
     }'
fieldsarray of string | null

Restrict the returned fields. Omit for the full record.

idsarray of string, ≥ 1, ≤ 100required

Headers

Idempotency-Keystring

Makes a retry safe. Send a unique value per request and reuse it when you retry that same request: with the same body and credential, on the same UTC day, rows already charged are not charged again.

attributionarray of Attribution
as_ofstring | null
domainstring | null
quotestring | null

RESERVED for per-fact citation. Always null in v1.

source_corpusSourceCorpus

Where content came from. Closed set — it appears in attribution[]. The first four are the GTM entity graph. The rest are the document corpora behind the non-entity categories, each a distinct index with its own refresh cadence — which is the reason they are named separately rather than lumped under one label: attribution[].as_of means nothing if two corpora updated a month apart share a name.

urlstring | null

RESERVED for per-fact citation. Always null in v1.

columnsarray of object | null

The answer table's columns, in order, when a run carries extra columns beyond the entity's own fields -- a job-opening link, a value joined from another dataset. Each entry is {name, description, source}; the value for each sits on every row in results keyed by the column name. Null means a plain entity table. Additive, so it breaks no existing client.

coverageCoverage | null

How much of the addressable set this answer represents. Null means coverage was not measured for this request -- fast and auto do not enumerate -- and never that coverage was zero. Additive, so it breaks no existing client.

auditedbooleandefault: false

Whether the query was checked against the executed filter for dropped requirements. Reported because an empty constraints_unmet only means something if something looked.

constraints_unmetarray of string

Requirements in your query that the search could not express, in your own words. Non-empty means part of the question was not answered -- most often because it needs a dataset this search cannot reach (job postings, employment history, patents, news, funding dates). When this is non-empty, universe_exhausted is withheld: 'we returned everything that matches' cannot be true of a question that was never asked.

criteriaarray of object

Per criterion: evaluated, passed, success_rate, and whether it was *proven* by the query or *judged* by a model. Without this a thin result leaves the caller guessing which requirement thinned it.

enumeratedinteger

How many of them this answer carries. ≥ 0.

enumeration_recallnumber | null

enumerated / universe. Null when the universe was not exact, because a ratio over an estimate is not a recall figure. Note this measures coverage of the *resolved query*, not of the user's intent -- a wrong predicate can be exhaustively enumerated. ≥ 0, ≤ 1.

linkagearray of object

One entry per other dataset this answer joined against: corpus, join_key, observable, of_constrained, ratio, is_lower_bound. ratio is the fraction of your matching accounts that dataset can even see -- measured at 5-60% depending on the dataset and how large the companies are, and never 100%. Non-empty therefore means universe_exhausted is withheld by construction: we returned everything reachable, and a dataset cannot see the rest.

linkage_coveragenumber | null

The joins combined, as a product rather than a minimum: two datasets seeing 27% and 24% of your accounts jointly see about 6.5%, not 24%. Null when no join was performed or when any leg's coverage is unknown.

linkage_coverage_is_lower_boundbooleandefault: false

True when a key set was capped or coverage was estimated rather than measured, making linkage_coverage a floor. Narrowing the question makes it exact.

similarityarray of object

Narrowings done by ranking rather than by predicate. Each entry carries the concept, how many ids it resolved to, the k asked for, whether the list was cut at that ceiling, and the fraction of candidates that could be compared at all. Non-empty means universe_exhausted is withheld on purpose: a cosine is a degree, so a top-k ranking has no complete state, and 2.9% of companies carry no embedding to compare.

truncated_bystring | null

Which limit stopped the enumeration short, when one did.

universeinteger

Records matching the resolved query, counted, not sampled. ≥ 0.

universe_exhaustedbooleandefault: false

Every matching record was returned and the count agrees. The claim an unbounded-corpus search engine cannot make.

universe_is_exactboolean

False when the count hit a cap. Always serialized: a capped count presented as exact is the same lie as an unmeasured one.

degradationarray of Degradation
detailstring
impact"recall" | "precision" | "freshness" | "fields"
reasonDegradationReason

Why an answer is less than it should be. Closed, because a client that cannot branch on the reason can only show the user a shrug. These are the honest constraints — partial vector coverage, smry mapped as keyword so it cannot be scored lexically, a federated corpus being unreachable — surfaced at runtime instead of in a footnote.

source_corpusSourceCorpus | null
has_moreboolean
metaResponseMeta

Present on every 2xx, including the ones that are not paginated.

as_ofstring
credential"api_key" | "session"default: api_key

Which credential produced this response. session means the dashboard playground ran it as the signed-in user rather than as an API key — so it is billed to the user, subject to interactive rate limits, and carries no integration compatibility guarantee. Additive and defaulted, so it breaks no existing client.

credits_chargednumber | null

What this request cost, in credits, to at most three decimals. 0 when it cost nothing: a Basic or AI search that found nothing, rows this search already paid for (a cursor sent again, or a request repeated with the same Idempotency-Key on the same UTC day), or a test key. A request without a cursor or a repeated key is a new search, so keep the first page rather than asking for it again. null on a free endpoint.

environment"live" | "test"

Echoed on every response so a developer can never mistake a test-key result for a live one.

request_idstring
next_cursorstring | null

Opaque and signed. Invariant: has_more == (next_cursor is not None). There is no page or offset parameter — not accepted, not deprecated, never present.

resolved_searchResolvedSearch | null
categoryEntityCategory

*What* to search, and what a returned row is. One parameter carries both, because they are the same fact: a search of patent returns patents. The alternative — a source/vertical selector beside a narrower category — lets a caller ask for patents from the people index, a combination that has no meaning and would need rejecting at runtime. A closed set that cannot express the contradiction is better than a validator that catches it. Values are exactly prism's own row types, so category in the request and results[].category in the response are always the same string. company and person are the GTM index; the rest are separate corpora with their own filters, freshness and coverage. Not everything applies everywhere: see SearchRequest, which rejects the GTM-only parameters rather than ignoring them. job_opening is a document corpus like patent/news_article/etc — a posting, not an entity — but its records carry a domain (the posting company's) all the same. It is deliberately not in GTM_CATEGORIES (that set is about the entity/document distinction, and a job posting is still a document), but it *is* in DOMAIN_FILTERABLE_CATEGORIES, which exists specifically to separate those two axes.

conflictsarray of object
filtersFilters
filters_source"caller" | "parser" | "caller+parser" | "none"default: none
mode"fast" | "auto" | "deep"

How hard to work on the query. The distinction is *what the words mean*, not how many results come back: - fast — match my words. The query is matched by meaning (vector retrieval, falling back to keywords where vectors are unavailable); no LLM in the path, so nothing is extracted into filters. - auto — understand my intent. The parser extracts filters. - deep — reason about it. Multi-step, slowest, most expensive. fast was very nearly defined as "filters only, no LLM", which would have made query — the primary parameter — silently inert. A parameter that does nothing is worse than one that is missing.

overridesarray of object
parser_versionstring
querystring | null
semantic_querystring | null
semantic_scope"company" | "person" | null
sortarray of object
resultsarray of EntityHit[PatentRecord]
categoryEntityCategory

*What* to search, and what a returned row is. One parameter carries both, because they are the same fact: a search of patent returns patents. The alternative — a source/vertical selector beside a narrower category — lets a caller ask for patents from the people index, a combination that has no meaning and would need rejecting at runtime. A closed set that cannot express the contradiction is better than a validator that catches it. Values are exactly prism's own row types, so category in the request and results[].category in the response are always the same string. company and person are the GTM index; the rest are separate corpora with their own filters, freshness and coverage. Not everything applies everywhere: see SearchRequest, which rejects the GTM-only parameters rather than ignoring them. job_opening is a document corpus like patent/news_article/etc — a posting, not an entity — but its records carry a domain (the posting company's) all the same. It is deliberately not in GTM_CATEGORIES (that set is about the entity/document distinction, and a job posting is still a document), but it *is* in DOMAIN_FILTERABLE_CATEGORIES, which exists specifically to separate those two axes.

foundboolean
idstring
matchesarray of PatentRecord
abstractstring | null
applicantsarray of PatentApplicant
company_connectionPatentCompanyConnection | null
company_idstring | null
countryPatentCountry | null
codestring | null
namestring | null
namestring | null
applicationPatentApplication | null
filedstring | null
kind_codestring | null
numberstring | null
officestring | null
office_namestring | null
typestring | null
classificationarray of string
classification_detailarray of PatentClassificationDetail
codestring | null
definitionstring | null
created_atstring | null
family_numberstring | null
granted_datestring | null
inventorsarray of PatentInventor
namestring | null
patent_idstring | null
priorityarray of PatentPriorityFiling
datestring | null
numberstring | null
publicationsarray of PatentPublication
datestring | null
grantedstring | null
kind_codestring | null
numberstring | null
statusstring | null
status"granted" | "applied" | "unknown" | null
tagsarray of string
titlestring | null
suggestionSearchSuggestion | null

A better way to have asked this question -- a different category (kind: search), or agentic search via POST /v1/agents (kind: agentic). Advisory: these results came from the search that was asked for, whatever this says. Null when there is nothing worth suggesting, which is the common case. Additive, so it breaks no existing client.

categoryEntityCategory | null

The category to search instead. Set iff kind is search.

kind"search" | "agentic"

search — a different category fits. agentic — no single search fits; use POST /v1/agents.

messagestring

One ready-to-show sentence.

totalinteger

≥ 0.

total_is_estimateboolean

Always serialized, never defaulted away. A field clients can forget exists is a field that renders an estimate as exact.

The ids are trend names.

curl -X POST "https://api.sproutsdata.ai/v1/entities/trends" \
  -H "X-API-Key: $SPROUTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "ids": [
         "Generative AI"
       ]
     }'
fieldsarray of string | null

Restrict the returned fields. Omit for the full record.

idsarray of string, ≥ 1, ≤ 100required

Headers

Idempotency-Keystring

Makes a retry safe. Send a unique value per request and reuse it when you retry that same request: with the same body and credential, on the same UTC day, rows already charged are not charged again.

attributionarray of Attribution
as_ofstring | null
domainstring | null
quotestring | null

RESERVED for per-fact citation. Always null in v1.

source_corpusSourceCorpus

Where content came from. Closed set — it appears in attribution[]. The first four are the GTM entity graph. The rest are the document corpora behind the non-entity categories, each a distinct index with its own refresh cadence — which is the reason they are named separately rather than lumped under one label: attribution[].as_of means nothing if two corpora updated a month apart share a name.

urlstring | null

RESERVED for per-fact citation. Always null in v1.

columnsarray of object | null

The answer table's columns, in order, when a run carries extra columns beyond the entity's own fields -- a job-opening link, a value joined from another dataset. Each entry is {name, description, source}; the value for each sits on every row in results keyed by the column name. Null means a plain entity table. Additive, so it breaks no existing client.

coverageCoverage | null

How much of the addressable set this answer represents. Null means coverage was not measured for this request -- fast and auto do not enumerate -- and never that coverage was zero. Additive, so it breaks no existing client.

auditedbooleandefault: false

Whether the query was checked against the executed filter for dropped requirements. Reported because an empty constraints_unmet only means something if something looked.

constraints_unmetarray of string

Requirements in your query that the search could not express, in your own words. Non-empty means part of the question was not answered -- most often because it needs a dataset this search cannot reach (job postings, employment history, patents, news, funding dates). When this is non-empty, universe_exhausted is withheld: 'we returned everything that matches' cannot be true of a question that was never asked.

criteriaarray of object

Per criterion: evaluated, passed, success_rate, and whether it was *proven* by the query or *judged* by a model. Without this a thin result leaves the caller guessing which requirement thinned it.

enumeratedinteger

How many of them this answer carries. ≥ 0.

enumeration_recallnumber | null

enumerated / universe. Null when the universe was not exact, because a ratio over an estimate is not a recall figure. Note this measures coverage of the *resolved query*, not of the user's intent -- a wrong predicate can be exhaustively enumerated. ≥ 0, ≤ 1.

linkagearray of object

One entry per other dataset this answer joined against: corpus, join_key, observable, of_constrained, ratio, is_lower_bound. ratio is the fraction of your matching accounts that dataset can even see -- measured at 5-60% depending on the dataset and how large the companies are, and never 100%. Non-empty therefore means universe_exhausted is withheld by construction: we returned everything reachable, and a dataset cannot see the rest.

linkage_coveragenumber | null

The joins combined, as a product rather than a minimum: two datasets seeing 27% and 24% of your accounts jointly see about 6.5%, not 24%. Null when no join was performed or when any leg's coverage is unknown.

linkage_coverage_is_lower_boundbooleandefault: false

True when a key set was capped or coverage was estimated rather than measured, making linkage_coverage a floor. Narrowing the question makes it exact.

similarityarray of object

Narrowings done by ranking rather than by predicate. Each entry carries the concept, how many ids it resolved to, the k asked for, whether the list was cut at that ceiling, and the fraction of candidates that could be compared at all. Non-empty means universe_exhausted is withheld on purpose: a cosine is a degree, so a top-k ranking has no complete state, and 2.9% of companies carry no embedding to compare.

truncated_bystring | null

Which limit stopped the enumeration short, when one did.

universeinteger

Records matching the resolved query, counted, not sampled. ≥ 0.

universe_exhaustedbooleandefault: false

Every matching record was returned and the count agrees. The claim an unbounded-corpus search engine cannot make.

universe_is_exactboolean

False when the count hit a cap. Always serialized: a capped count presented as exact is the same lie as an unmeasured one.

degradationarray of Degradation
detailstring
impact"recall" | "precision" | "freshness" | "fields"
reasonDegradationReason

Why an answer is less than it should be. Closed, because a client that cannot branch on the reason can only show the user a shrug. These are the honest constraints — partial vector coverage, smry mapped as keyword so it cannot be scored lexically, a federated corpus being unreachable — surfaced at runtime instead of in a footnote.

source_corpusSourceCorpus | null
has_moreboolean
metaResponseMeta

Present on every 2xx, including the ones that are not paginated.

as_ofstring
credential"api_key" | "session"default: api_key

Which credential produced this response. session means the dashboard playground ran it as the signed-in user rather than as an API key — so it is billed to the user, subject to interactive rate limits, and carries no integration compatibility guarantee. Additive and defaulted, so it breaks no existing client.

credits_chargednumber | null

What this request cost, in credits, to at most three decimals. 0 when it cost nothing: a Basic or AI search that found nothing, rows this search already paid for (a cursor sent again, or a request repeated with the same Idempotency-Key on the same UTC day), or a test key. A request without a cursor or a repeated key is a new search, so keep the first page rather than asking for it again. null on a free endpoint.

environment"live" | "test"

Echoed on every response so a developer can never mistake a test-key result for a live one.

request_idstring
next_cursorstring | null

Opaque and signed. Invariant: has_more == (next_cursor is not None). There is no page or offset parameter — not accepted, not deprecated, never present.

resolved_searchResolvedSearch | null
categoryEntityCategory

*What* to search, and what a returned row is. One parameter carries both, because they are the same fact: a search of patent returns patents. The alternative — a source/vertical selector beside a narrower category — lets a caller ask for patents from the people index, a combination that has no meaning and would need rejecting at runtime. A closed set that cannot express the contradiction is better than a validator that catches it. Values are exactly prism's own row types, so category in the request and results[].category in the response are always the same string. company and person are the GTM index; the rest are separate corpora with their own filters, freshness and coverage. Not everything applies everywhere: see SearchRequest, which rejects the GTM-only parameters rather than ignoring them. job_opening is a document corpus like patent/news_article/etc — a posting, not an entity — but its records carry a domain (the posting company's) all the same. It is deliberately not in GTM_CATEGORIES (that set is about the entity/document distinction, and a job posting is still a document), but it *is* in DOMAIN_FILTERABLE_CATEGORIES, which exists specifically to separate those two axes.

conflictsarray of object
filtersFilters
filters_source"caller" | "parser" | "caller+parser" | "none"default: none
mode"fast" | "auto" | "deep"

How hard to work on the query. The distinction is *what the words mean*, not how many results come back: - fast — match my words. The query is matched by meaning (vector retrieval, falling back to keywords where vectors are unavailable); no LLM in the path, so nothing is extracted into filters. - auto — understand my intent. The parser extracts filters. - deep — reason about it. Multi-step, slowest, most expensive. fast was very nearly defined as "filters only, no LLM", which would have made query — the primary parameter — silently inert. A parameter that does nothing is worse than one that is missing.

overridesarray of object
parser_versionstring
querystring | null
semantic_querystring | null
semantic_scope"company" | "person" | null
sortarray of object
resultsarray of EntityHit[TrendRecord]
categoryEntityCategory

*What* to search, and what a returned row is. One parameter carries both, because they are the same fact: a search of patent returns patents. The alternative — a source/vertical selector beside a narrower category — lets a caller ask for patents from the people index, a combination that has no meaning and would need rejecting at runtime. A closed set that cannot express the contradiction is better than a validator that catches it. Values are exactly prism's own row types, so category in the request and results[].category in the response are always the same string. company and person are the GTM index; the rest are separate corpora with their own filters, freshness and coverage. Not everything applies everywhere: see SearchRequest, which rejects the GTM-only parameters rather than ignoring them. job_opening is a document corpus like patent/news_article/etc — a posting, not an entity — but its records carry a domain (the posting company's) all the same. It is deliberately not in GTM_CATEGORIES (that set is about the entity/document distinction, and a job posting is still a document), but it *is* in DOMAIN_FILTERABLE_CATEGORIES, which exists specifically to separate those two axes.

foundboolean
idstring
matchesarray of TrendRecord
badgesTrendBadges | null
fifteen_percentarray of string
five_percentarray of string
ten_percentarray of string
biggest_investorsarray of TrendInvestor
companies_invested_inarray of TrendInvestorCompany
invested_sumnumber | null
namestring | null
investednumber | null
namestring | null
roundsinteger | null
connectionsarray of TrendConnection
overlapnumber | null
shared_companiesinteger | null
trendstring | null
countriesarray of string
created_atstring | null
descriptionTrendDescription | null
longstring | null
shortstring | null
distributionsTrendDistributions | null
employee_growthTrendDistribution | null
boxplotTrendBoxplot | null
maximumnumber | null
mediannumber | null
minimumnumber | null
quartilesarray of TrendQuartile
stdnumber | null
top_companiesarray of TrendNamedTotal
variancenumber | null
fundingTrendDistribution | null
boxplotTrendBoxplot | null
maximumnumber | null
mediannumber | null
minimumnumber | null
quartilesarray of TrendQuartile
stdnumber | null
top_companiesarray of TrendNamedTotal
variancenumber | null
manpowerTrendDistribution | null
boxplotTrendBoxplot | null
maximumnumber | null
mediannumber | null
minimumnumber | null
quartilesarray of TrendQuartile
stdnumber | null
top_companiesarray of TrendNamedTotal
variancenumber | null
revenueTrendDistribution | null
boxplotTrendBoxplot | null
maximumnumber | null
mediannumber | null
minimumnumber | null
quartilesarray of TrendQuartile
stdnumber | null
top_companiesarray of TrendNamedTotal
variancenumber | null
featuresTrendFeatures | null
academic_activitiesarray of TrendFeature
namestring | null
sizestring | null
size_cleanednumber | null
sourcearray of string
acquisitionsarray of TrendDeal
amountnumber | null
buyersarray of TrendCompanyRef
companiesarray of TrendCompanyRef
datestring | null
investorsarray of TrendCompanyRef
projectstring | null
recipientsarray of TrendCompanyRef
sharestring | null
share_percentagenumber | null
sourcearray of string
targetsarray of TrendCompanyRef
application_areasarray of TrendFeature
namestring | null
sizestring | null
size_cleanednumber | null
sourcearray of string
branding_and_messagingarray of string
business_classificationarray of string
business_modelsarray of string
community_engagementarray of TrendFeature
namestring | null
sizestring | null
size_cleanednumber | null
sourcearray of string
core_technologiesarray of TrendFeature
namestring | null
sizestring | null
size_cleanednumber | null
sourcearray of string
customer_relationship_focusarray of TrendFeature
namestring | null
sizestring | null
size_cleanednumber | null
sourcearray of string
customer_segmentsarray of TrendFeature
namestring | null
sizestring | null
size_cleanednumber | null
sourcearray of string
education_and_trainingarray of TrendFeature
namestring | null
sizestring | null
size_cleanednumber | null
sourcearray of string
government_initiativesarray of TrendFeature
namestring | null
sizestring | null
size_cleanednumber | null
sourcearray of string
industry_eventsarray of TrendFeature
namestring | null
sizestring | null
size_cleanednumber | null
sourcearray of string
investments_and_rndarray of TrendDeal
amountnumber | null
buyersarray of TrendCompanyRef
companiesarray of TrendCompanyRef
datestring | null
investorsarray of TrendCompanyRef
projectstring | null
recipientsarray of TrendCompanyRef
sharestring | null
share_percentagenumber | null
sourcearray of string
targetsarray of TrendCompanyRef
market_challengesarray of TrendFeature
namestring | null
sizestring | null
size_cleanednumber | null
sourcearray of string
market_concentrationarray of TrendDeal
amountnumber | null
buyersarray of TrendCompanyRef
companiesarray of TrendCompanyRef
datestring | null
investorsarray of TrendCompanyRef
projectstring | null
recipientsarray of TrendCompanyRef
sharestring | null
share_percentagenumber | null
sourcearray of string
targetsarray of TrendCompanyRef
market_driversarray of TrendFeature
namestring | null
sizestring | null
size_cleanednumber | null
sourcearray of string
market_segmentsarray of TrendFeature
namestring | null
sizestring | null
size_cleanednumber | null
sourcearray of string
partnerships_and_alliancesarray of TrendDeal
amountnumber | null
buyersarray of TrendCompanyRef
companiesarray of TrendCompanyRef
datestring | null
investorsarray of TrendCompanyRef
projectstring | null
recipientsarray of TrendCompanyRef
sharestring | null
share_percentagenumber | null
sourcearray of string
targetsarray of TrendCompanyRef
regulatory_challengesarray of TrendFeature
namestring | null
sizestring | null
size_cleanednumber | null
sourcearray of string
standards_and_certificationsarray of TrendFeature
namestring | null
sizestring | null
size_cleanednumber | null
sourcearray of string
technology_limitationsarray of TrendFeature
namestring | null
sizestring | null
size_cleanednumber | null
sourcearray of string
trends_and_insightsarray of TrendFeature
namestring | null
sizestring | null
size_cleanednumber | null
sourcearray of string
unique_value_propositionarray of TrendFeature
namestring | null
sizestring | null
size_cleanednumber | null
sourcearray of string
graphsTrendGraphs | null
article_startup_global_searcharray of TrendGraphPoint
datestring | null
relative_frequencynumber | null
funding_raisedarray of TrendGraphPoint
datestring | null
relative_frequencynumber | null
global_searcharray of TrendGraphPoint
datestring | null
relative_frequencynumber | null
new_companiesarray of TrendGraphPoint
datestring | null
relative_frequencynumber | null
news_coveragearray of TrendGraphPoint
datestring | null
relative_frequencynumber | null
patents_applicationarray of TrendGraphPoint
datestring | null
relative_frequencynumber | null
patents_publicationarray of TrendGraphPoint
datestring | null
relative_frequencynumber | null
highlightsarray of object
industriesarray of string
marketTrendMarket | null
cagrTrendMarketCagr | null
percentnumber | null
sourcearray of string
valuestring | null
forecastTrendMarketSize | null
amountnumber | null
sourcearray of string
yearstring | null
sizeTrendMarketSize | null
amountnumber | null
sourcearray of string
yearstring | null
patent_statsTrendPatentStats | null
all_applicantsTrendMetric | null
percentilenumber | null
rankinteger | null
valuenumber | null
all_classificationsTrendMetric | null
percentilenumber | null
rankinteger | null
valuenumber | null
all_patentsTrendMetric | null
percentilenumber | null
rankinteger | null
valuenumber | null
applications_growthnumber | null
applications_growth_in_periodnumber | null
growth_categorystring | null
magnitudeTrendMetric | null
percentilenumber | null
rankinteger | null
valuenumber | null
median_patent_ageTrendMetric | null
percentilenumber | null
rankinteger | null
valuenumber | null
publication_growthnumber | null
publication_growth_in_periodnumber | null
top_applicantstring | null
top_inventorstring | null
top_issuerstring | null
yearly_growthTrendMetric | null
percentilenumber | null
rankinteger | null
valuenumber | null
publicationsarray of TrendCategoryCount
countinteger | null
namestring | null
relation_scorenumber | null
scaleTrendScale | null
article_coverageTrendMetric | null
percentilenumber | null
rankinteger | null
valuenumber | null
companiesinteger | null
employee_growthTrendTotalAverage | null
averagenumber | null
rank_percentilenumber | null
totalnumber | null
fundingTrendFunding | null
averagenumber | null
average_per_roundnumber | null
rank_percentilenumber | null
roundsinteger | null
rounds_percentilenumber | null
totalnumber | null
unique_investorsinteger | null
manpowerTrendTotalAverage | null
averagenumber | null
rank_percentilenumber | null
totalnumber | null
patentsTrendTotalAverage | null
averagenumber | null
rank_percentilenumber | null
totalnumber | null
revenueTrendTotalAverage | null
averagenumber | null
rank_percentilenumber | null
totalnumber | null
search_interestTrendSearchInterest | null
article_startup_growthnumber | null
article_startup_growth_in_periodnumber | null
article_startup_growth_in_period_categorystring | null
average_volumeTrendMetric | null
percentilenumber | null
rankinteger | null
valuenumber | null
growthnumber | null
growth_categorystring | null
growth_in_periodnumber | null
hype_strengthstring | null
magnitudeTrendMetric | null
percentilenumber | null
rankinteger | null
valuenumber | null
technology_adoption_valuenumber | null
trendingnumber | null
trending_categorystring | null
yearly_growthTrendMetric | null
percentilenumber | null
rankinteger | null
valuenumber | null
signalsTrendSignals | null
article_ageTrendMetric | null
percentilenumber | null
rankinteger | null
valuenumber | null
company_ageTrendMetric | null
percentilenumber | null
rankinteger | null
valuenumber | null
company_magnitudeTrendMetric | null
percentilenumber | null
rankinteger | null
valuenumber | null
growthTrendGrowth | null
annualizedTrendGrowthAnnualized | null
over_windowTrendGrowthOverWindow | null
hypenumber | null
magnitudeTrendBand | null
categorystring | null
percentilenumber | null
valuenumber | null
maturityTrendBand | null
categorystring | null
percentilenumber | null
valuenumber | null
news_magnitudeTrendMetric | null
percentilenumber | null
rankinteger | null
valuenumber | null
signal_strengthstring | null
technology_adoptionstring | null
trend_ageTrendAgeMetric | null
categorystring | null
percentilenumber | null
rankinteger | null
valuenumber | null
similar_tagsarray of TrendSimilarTag
countinteger | null
namestring | null
relation_scorenumber | null
relative_percentagenumber | null
snapshotTrendSnapshot | null
average_invested_sum_per_investornumber | null
companies_growth_categorystring | null
company_maturityTrendCompanyMaturity | null
categorystring | null
valuenumber | null
funding_growth_in_periodnumber | null
funding_roundsarray of TrendCategoryCount
countinteger | null
namestring | null
relation_scorenumber | null
grantsTrendTotalAverage | null
averagenumber | null
rank_percentilenumber | null
totalnumber | null
growth_periodnumber | null
invested_companiesTrendInvestedCompanies | null
percentage_availablenumber | null
total_availabilitynumber | null
investment_rounds_per_investornumber | null
most_common_company_stageTrendCategoryCount | null
countinteger | null
namestring | null
relation_scorenumber | null
most_frequently_mentioned_companiesarray of string
news_frequencynumber | null
news_growth_categorystring | null
spreadTrendMetric | null
percentilenumber | null
rankinteger | null
valuenumber | null
youngest_articlesarray of TrendYoungestArticle
article_datestring | null
article_linkstring | null
article_namestring | null
youngest_companiesarray of TrendYoungestCompany
company_datestring | null
company_idstring | null
startupsarray of TrendStartup
domainstring | null
scorenumber | null
summaryTrendSummary | null
companies_involvedstring | null
concise_descriptionstring | null
conclusion_and_key_takeawaysstring | null
growth_evaluationstring | null
introductionstring | null
investment_and_fundingstring | null
key_topics_and_trendsstring | null
market_overviewstring | null
news_and_media_coveragestring | null
technology_usedstring | null
topic_analysisstring | null
topic_typestring | null
trendstring | null
suggestionSearchSuggestion | null

A better way to have asked this question -- a different category (kind: search), or agentic search via POST /v1/agents (kind: agentic). Advisory: these results came from the search that was asked for, whatever this says. Null when there is nothing worth suggesting, which is the common case. Additive, so it breaks no existing client.

categoryEntityCategory | null

The category to search instead. Set iff kind is search.

kind"search" | "agentic"

search — a different category fits. agentic — no single search fits; use POST /v1/agents.

messagestring

One ready-to-show sentence.

totalinteger

≥ 0.

total_is_estimateboolean

Always serialized, never defaulted away. A field clients can forget exists is a field that renders an estimate as exact.

Academic reports#

The ids are DOIs, written as https://doi.org/... URLs.

curl -X POST "https://api.sproutsdata.ai/v1/entities/academic-reports" \
  -H "X-API-Key: $SPROUTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "ids": [
         "https://doi.org/10.1000/xyz123"
       ]
     }'
fieldsarray of string | null

Restrict the returned fields. Omit for the full record.

idsarray of string, ≥ 1, ≤ 100required

Headers

Idempotency-Keystring

Makes a retry safe. Send a unique value per request and reuse it when you retry that same request: with the same body and credential, on the same UTC day, rows already charged are not charged again.

attributionarray of Attribution
as_ofstring | null
domainstring | null
quotestring | null

RESERVED for per-fact citation. Always null in v1.

source_corpusSourceCorpus

Where content came from. Closed set — it appears in attribution[]. The first four are the GTM entity graph. The rest are the document corpora behind the non-entity categories, each a distinct index with its own refresh cadence — which is the reason they are named separately rather than lumped under one label: attribution[].as_of means nothing if two corpora updated a month apart share a name.

urlstring | null

RESERVED for per-fact citation. Always null in v1.

columnsarray of object | null

The answer table's columns, in order, when a run carries extra columns beyond the entity's own fields -- a job-opening link, a value joined from another dataset. Each entry is {name, description, source}; the value for each sits on every row in results keyed by the column name. Null means a plain entity table. Additive, so it breaks no existing client.

coverageCoverage | null

How much of the addressable set this answer represents. Null means coverage was not measured for this request -- fast and auto do not enumerate -- and never that coverage was zero. Additive, so it breaks no existing client.

auditedbooleandefault: false

Whether the query was checked against the executed filter for dropped requirements. Reported because an empty constraints_unmet only means something if something looked.

constraints_unmetarray of string

Requirements in your query that the search could not express, in your own words. Non-empty means part of the question was not answered -- most often because it needs a dataset this search cannot reach (job postings, employment history, patents, news, funding dates). When this is non-empty, universe_exhausted is withheld: 'we returned everything that matches' cannot be true of a question that was never asked.

criteriaarray of object

Per criterion: evaluated, passed, success_rate, and whether it was *proven* by the query or *judged* by a model. Without this a thin result leaves the caller guessing which requirement thinned it.

enumeratedinteger

How many of them this answer carries. ≥ 0.

enumeration_recallnumber | null

enumerated / universe. Null when the universe was not exact, because a ratio over an estimate is not a recall figure. Note this measures coverage of the *resolved query*, not of the user's intent -- a wrong predicate can be exhaustively enumerated. ≥ 0, ≤ 1.

linkagearray of object

One entry per other dataset this answer joined against: corpus, join_key, observable, of_constrained, ratio, is_lower_bound. ratio is the fraction of your matching accounts that dataset can even see -- measured at 5-60% depending on the dataset and how large the companies are, and never 100%. Non-empty therefore means universe_exhausted is withheld by construction: we returned everything reachable, and a dataset cannot see the rest.

linkage_coveragenumber | null

The joins combined, as a product rather than a minimum: two datasets seeing 27% and 24% of your accounts jointly see about 6.5%, not 24%. Null when no join was performed or when any leg's coverage is unknown.

linkage_coverage_is_lower_boundbooleandefault: false

True when a key set was capped or coverage was estimated rather than measured, making linkage_coverage a floor. Narrowing the question makes it exact.

similarityarray of object

Narrowings done by ranking rather than by predicate. Each entry carries the concept, how many ids it resolved to, the k asked for, whether the list was cut at that ceiling, and the fraction of candidates that could be compared at all. Non-empty means universe_exhausted is withheld on purpose: a cosine is a degree, so a top-k ranking has no complete state, and 2.9% of companies carry no embedding to compare.

truncated_bystring | null

Which limit stopped the enumeration short, when one did.

universeinteger

Records matching the resolved query, counted, not sampled. ≥ 0.

universe_exhaustedbooleandefault: false

Every matching record was returned and the count agrees. The claim an unbounded-corpus search engine cannot make.

universe_is_exactboolean

False when the count hit a cap. Always serialized: a capped count presented as exact is the same lie as an unmeasured one.

degradationarray of Degradation
detailstring
impact"recall" | "precision" | "freshness" | "fields"
reasonDegradationReason

Why an answer is less than it should be. Closed, because a client that cannot branch on the reason can only show the user a shrug. These are the honest constraints — partial vector coverage, smry mapped as keyword so it cannot be scored lexically, a federated corpus being unreachable — surfaced at runtime instead of in a footnote.

source_corpusSourceCorpus | null
has_moreboolean
metaResponseMeta

Present on every 2xx, including the ones that are not paginated.

as_ofstring
credential"api_key" | "session"default: api_key

Which credential produced this response. session means the dashboard playground ran it as the signed-in user rather than as an API key — so it is billed to the user, subject to interactive rate limits, and carries no integration compatibility guarantee. Additive and defaulted, so it breaks no existing client.

credits_chargednumber | null

What this request cost, in credits, to at most three decimals. 0 when it cost nothing: a Basic or AI search that found nothing, rows this search already paid for (a cursor sent again, or a request repeated with the same Idempotency-Key on the same UTC day), or a test key. A request without a cursor or a repeated key is a new search, so keep the first page rather than asking for it again. null on a free endpoint.

environment"live" | "test"

Echoed on every response so a developer can never mistake a test-key result for a live one.

request_idstring
next_cursorstring | null

Opaque and signed. Invariant: has_more == (next_cursor is not None). There is no page or offset parameter — not accepted, not deprecated, never present.

resolved_searchResolvedSearch | null
categoryEntityCategory

*What* to search, and what a returned row is. One parameter carries both, because they are the same fact: a search of patent returns patents. The alternative — a source/vertical selector beside a narrower category — lets a caller ask for patents from the people index, a combination that has no meaning and would need rejecting at runtime. A closed set that cannot express the contradiction is better than a validator that catches it. Values are exactly prism's own row types, so category in the request and results[].category in the response are always the same string. company and person are the GTM index; the rest are separate corpora with their own filters, freshness and coverage. Not everything applies everywhere: see SearchRequest, which rejects the GTM-only parameters rather than ignoring them. job_opening is a document corpus like patent/news_article/etc — a posting, not an entity — but its records carry a domain (the posting company's) all the same. It is deliberately not in GTM_CATEGORIES (that set is about the entity/document distinction, and a job posting is still a document), but it *is* in DOMAIN_FILTERABLE_CATEGORIES, which exists specifically to separate those two axes.

conflictsarray of object
filtersFilters
filters_source"caller" | "parser" | "caller+parser" | "none"default: none
mode"fast" | "auto" | "deep"

How hard to work on the query. The distinction is *what the words mean*, not how many results come back: - fast — match my words. The query is matched by meaning (vector retrieval, falling back to keywords where vectors are unavailable); no LLM in the path, so nothing is extracted into filters. - auto — understand my intent. The parser extracts filters. - deep — reason about it. Multi-step, slowest, most expensive. fast was very nearly defined as "filters only, no LLM", which would have made query — the primary parameter — silently inert. A parameter that does nothing is worse than one that is missing.

overridesarray of object
parser_versionstring
querystring | null
semantic_querystring | null
semantic_scope"company" | "person" | null
sortarray of object
resultsarray of EntityHit[AcademicReportRecord]
categoryEntityCategory

*What* to search, and what a returned row is. One parameter carries both, because they are the same fact: a search of patent returns patents. The alternative — a source/vertical selector beside a narrower category — lets a caller ask for patents from the people index, a combination that has no meaning and would need rejecting at runtime. A closed set that cannot express the contradiction is better than a validator that catches it. Values are exactly prism's own row types, so category in the request and results[].category in the response are always the same string. company and person are the GTM index; the rest are separate corpora with their own filters, freshness and coverage. Not everything applies everywhere: see SearchRequest, which rejects the GTM-only parameters rather than ignoring them. job_opening is a document corpus like patent/news_article/etc — a posting, not an entity — but its records carry a domain (the posting company's) all the same. It is deliberately not in GTM_CATEGORIES (that set is about the entity/document distinction, and a job posting is still a document), but it *is* in DOMAIN_FILTERABLE_CATEGORIES, which exists specifically to separate those two axes.

foundboolean
idstring
matchesarray of AcademicReportRecord
abstractstring | null
authorsarray of AcademicAuthor
employmentstring | null
namestring | null
citation_countsAcademicCitationCounts | null
citationsinteger | null
referencesinteger | null
citationsarray of AcademicCitation
datestring | null
doistring | null
titlestring | null
doistring | null
full_textstring | null
funded_byarray of string
paper_typestring | null
published_datestring | null
publisherstring | null
referencesarray of AcademicReference
datestring | null
doistring | null
titlestring | null
tagsarray of string
titlestring | null
urlsarray of string
suggestionSearchSuggestion | null

A better way to have asked this question -- a different category (kind: search), or agentic search via POST /v1/agents (kind: agentic). Advisory: these results came from the search that was asked for, whatever this says. Null when there is nothing worth suggesting, which is the common case. Additive, so it breaks no existing client.

categoryEntityCategory | null

The category to search instead. Set iff kind is search.

kind"search" | "agentic"

search — a different category fits. agentic — no single search fits; use POST /v1/agents.

messagestring

One ready-to-show sentence.

totalinteger

≥ 0.

total_is_estimateboolean

Always serialized, never defaulted away. A field clients can forget exists is a field that renders an estimate as exact.

News#

With "by": "name" (the default), each value is searched against article headlines.

curl -X POST "https://api.sproutsdata.ai/v1/entities/news" \
  -H "X-API-Key: $SPROUTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "ids": [
         "Stripe"
       ],
       "by": "name"
     }'
by"id" | "name"default: name

How to interpret ids: "name" (default) treats each entry as a free-text name — an article headline, a report title, a job posting's role, or the company a funding round belongs to — and looks it up the way you'd look up a trend by name. "id" treats each entry as a prism id, same as every other category. The id on a search hit is an opaque hash, not a prism id, so it does not resolve here.

fieldsarray of string | null

Restrict the returned fields. Omit for the full record.

idsarray of string, ≥ 1, ≤ 100required

Headers

Idempotency-Keystring

Makes a retry safe. Send a unique value per request and reuse it when you retry that same request: with the same body and credential, on the same UTC day, rows already charged are not charged again.

attributionarray of Attribution
as_ofstring | null
domainstring | null
quotestring | null

RESERVED for per-fact citation. Always null in v1.

source_corpusSourceCorpus

Where content came from. Closed set — it appears in attribution[]. The first four are the GTM entity graph. The rest are the document corpora behind the non-entity categories, each a distinct index with its own refresh cadence — which is the reason they are named separately rather than lumped under one label: attribution[].as_of means nothing if two corpora updated a month apart share a name.

urlstring | null

RESERVED for per-fact citation. Always null in v1.

columnsarray of object | null

The answer table's columns, in order, when a run carries extra columns beyond the entity's own fields -- a job-opening link, a value joined from another dataset. Each entry is {name, description, source}; the value for each sits on every row in results keyed by the column name. Null means a plain entity table. Additive, so it breaks no existing client.

coverageCoverage | null

How much of the addressable set this answer represents. Null means coverage was not measured for this request -- fast and auto do not enumerate -- and never that coverage was zero. Additive, so it breaks no existing client.

auditedbooleandefault: false

Whether the query was checked against the executed filter for dropped requirements. Reported because an empty constraints_unmet only means something if something looked.

constraints_unmetarray of string

Requirements in your query that the search could not express, in your own words. Non-empty means part of the question was not answered -- most often because it needs a dataset this search cannot reach (job postings, employment history, patents, news, funding dates). When this is non-empty, universe_exhausted is withheld: 'we returned everything that matches' cannot be true of a question that was never asked.

criteriaarray of object

Per criterion: evaluated, passed, success_rate, and whether it was *proven* by the query or *judged* by a model. Without this a thin result leaves the caller guessing which requirement thinned it.

enumeratedinteger

How many of them this answer carries. ≥ 0.

enumeration_recallnumber | null

enumerated / universe. Null when the universe was not exact, because a ratio over an estimate is not a recall figure. Note this measures coverage of the *resolved query*, not of the user's intent -- a wrong predicate can be exhaustively enumerated. ≥ 0, ≤ 1.

linkagearray of object

One entry per other dataset this answer joined against: corpus, join_key, observable, of_constrained, ratio, is_lower_bound. ratio is the fraction of your matching accounts that dataset can even see -- measured at 5-60% depending on the dataset and how large the companies are, and never 100%. Non-empty therefore means universe_exhausted is withheld by construction: we returned everything reachable, and a dataset cannot see the rest.

linkage_coveragenumber | null

The joins combined, as a product rather than a minimum: two datasets seeing 27% and 24% of your accounts jointly see about 6.5%, not 24%. Null when no join was performed or when any leg's coverage is unknown.

linkage_coverage_is_lower_boundbooleandefault: false

True when a key set was capped or coverage was estimated rather than measured, making linkage_coverage a floor. Narrowing the question makes it exact.

similarityarray of object

Narrowings done by ranking rather than by predicate. Each entry carries the concept, how many ids it resolved to, the k asked for, whether the list was cut at that ceiling, and the fraction of candidates that could be compared at all. Non-empty means universe_exhausted is withheld on purpose: a cosine is a degree, so a top-k ranking has no complete state, and 2.9% of companies carry no embedding to compare.

truncated_bystring | null

Which limit stopped the enumeration short, when one did.

universeinteger

Records matching the resolved query, counted, not sampled. ≥ 0.

universe_exhaustedbooleandefault: false

Every matching record was returned and the count agrees. The claim an unbounded-corpus search engine cannot make.

universe_is_exactboolean

False when the count hit a cap. Always serialized: a capped count presented as exact is the same lie as an unmeasured one.

degradationarray of Degradation
detailstring
impact"recall" | "precision" | "freshness" | "fields"
reasonDegradationReason

Why an answer is less than it should be. Closed, because a client that cannot branch on the reason can only show the user a shrug. These are the honest constraints — partial vector coverage, smry mapped as keyword so it cannot be scored lexically, a federated corpus being unreachable — surfaced at runtime instead of in a footnote.

source_corpusSourceCorpus | null
has_moreboolean
metaResponseMeta

Present on every 2xx, including the ones that are not paginated.

as_ofstring
credential"api_key" | "session"default: api_key

Which credential produced this response. session means the dashboard playground ran it as the signed-in user rather than as an API key — so it is billed to the user, subject to interactive rate limits, and carries no integration compatibility guarantee. Additive and defaulted, so it breaks no existing client.

credits_chargednumber | null

What this request cost, in credits, to at most three decimals. 0 when it cost nothing: a Basic or AI search that found nothing, rows this search already paid for (a cursor sent again, or a request repeated with the same Idempotency-Key on the same UTC day), or a test key. A request without a cursor or a repeated key is a new search, so keep the first page rather than asking for it again. null on a free endpoint.

environment"live" | "test"

Echoed on every response so a developer can never mistake a test-key result for a live one.

request_idstring
next_cursorstring | null

Opaque and signed. Invariant: has_more == (next_cursor is not None). There is no page or offset parameter — not accepted, not deprecated, never present.

resolved_searchResolvedSearch | null
categoryEntityCategory

*What* to search, and what a returned row is. One parameter carries both, because they are the same fact: a search of patent returns patents. The alternative — a source/vertical selector beside a narrower category — lets a caller ask for patents from the people index, a combination that has no meaning and would need rejecting at runtime. A closed set that cannot express the contradiction is better than a validator that catches it. Values are exactly prism's own row types, so category in the request and results[].category in the response are always the same string. company and person are the GTM index; the rest are separate corpora with their own filters, freshness and coverage. Not everything applies everywhere: see SearchRequest, which rejects the GTM-only parameters rather than ignoring them. job_opening is a document corpus like patent/news_article/etc — a posting, not an entity — but its records carry a domain (the posting company's) all the same. It is deliberately not in GTM_CATEGORIES (that set is about the entity/document distinction, and a job posting is still a document), but it *is* in DOMAIN_FILTERABLE_CATEGORIES, which exists specifically to separate those two axes.

conflictsarray of object
filtersFilters
filters_source"caller" | "parser" | "caller+parser" | "none"default: none
mode"fast" | "auto" | "deep"

How hard to work on the query. The distinction is *what the words mean*, not how many results come back: - fast — match my words. The query is matched by meaning (vector retrieval, falling back to keywords where vectors are unavailable); no LLM in the path, so nothing is extracted into filters. - auto — understand my intent. The parser extracts filters. - deep — reason about it. Multi-step, slowest, most expensive. fast was very nearly defined as "filters only, no LLM", which would have made query — the primary parameter — silently inert. A parameter that does nothing is worse than one that is missing.

overridesarray of object
parser_versionstring
querystring | null
semantic_querystring | null
semantic_scope"company" | "person" | null
sortarray of object
resultsarray of EntityHit[NewsRecord]
categoryEntityCategory

*What* to search, and what a returned row is. One parameter carries both, because they are the same fact: a search of patent returns patents. The alternative — a source/vertical selector beside a narrower category — lets a caller ask for patents from the people index, a combination that has no meaning and would need rejecting at runtime. A closed set that cannot express the contradiction is better than a validator that catches it. Values are exactly prism's own row types, so category in the request and results[].category in the response are always the same string. company and person are the GTM index; the rest are separate corpora with their own filters, freshness and coverage. Not everything applies everywhere: see SearchRequest, which rejects the GTM-only parameters rather than ignoring them. job_opening is a document corpus like patent/news_article/etc — a posting, not an entity — but its records carry a domain (the posting company's) all the same. It is deliberately not in GTM_CATEGORIES (that set is about the entity/document distinction, and a job posting is still a document), but it *is* in DOMAIN_FILTERABLE_CATEGORIES, which exists specifically to separate those two axes.

foundboolean
idstring
matchesarray of NewsRecord
authorstring | null
companiesNewsCompanyLinks | null
direct_linkarray of NewsCompanyRef
domainstring | null
namestring | null
linkedarray of NewsCompanyRef
domainstring | null
namestring | null
contentstring | null
languagestring | null
linkstring | null
placesNewsPlaces | null
citiesarray of string
countriesarray of string
productsarray of string
publicationNewsPublication | null
domainstring | null
linkstring | null
popularity_rankstring | null
titlestring | null
published_atstring | null
summarystring | null
tagsarray of string
titlestring | null
updated_atstring | null
suggestionSearchSuggestion | null

A better way to have asked this question -- a different category (kind: search), or agentic search via POST /v1/agents (kind: agentic). Advisory: these results came from the search that was asked for, whatever this says. Null when there is nothing worth suggesting, which is the common case. Additive, so it breaks no existing client.

categoryEntityCategory | null

The category to search instead. Set iff kind is search.

kind"search" | "agentic"

search — a different category fits. agentic — no single search fits; use POST /v1/agents.

messagestring

One ready-to-show sentence.

totalinteger

≥ 0.

total_is_estimateboolean

Always serialized, never defaulted away. A field clients can forget exists is a field that renders an estimate as exact.

Market reports#

With "by": "name" (the default), each value is searched against report titles.

curl -X POST "https://api.sproutsdata.ai/v1/entities/market-reports" \
  -H "X-API-Key: $SPROUTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "ids": [
         "payments market"
       ],
       "by": "name"
     }'
by"id" | "name"default: name

How to interpret ids: "name" (default) treats each entry as a free-text name — an article headline, a report title, a job posting's role, or the company a funding round belongs to — and looks it up the way you'd look up a trend by name. "id" treats each entry as a prism id, same as every other category. The id on a search hit is an opaque hash, not a prism id, so it does not resolve here.

fieldsarray of string | null

Restrict the returned fields. Omit for the full record.

idsarray of string, ≥ 1, ≤ 100required

Headers

Idempotency-Keystring

Makes a retry safe. Send a unique value per request and reuse it when you retry that same request: with the same body and credential, on the same UTC day, rows already charged are not charged again.

attributionarray of Attribution
as_ofstring | null
domainstring | null
quotestring | null

RESERVED for per-fact citation. Always null in v1.

source_corpusSourceCorpus

Where content came from. Closed set — it appears in attribution[]. The first four are the GTM entity graph. The rest are the document corpora behind the non-entity categories, each a distinct index with its own refresh cadence — which is the reason they are named separately rather than lumped under one label: attribution[].as_of means nothing if two corpora updated a month apart share a name.

urlstring | null

RESERVED for per-fact citation. Always null in v1.

columnsarray of object | null

The answer table's columns, in order, when a run carries extra columns beyond the entity's own fields -- a job-opening link, a value joined from another dataset. Each entry is {name, description, source}; the value for each sits on every row in results keyed by the column name. Null means a plain entity table. Additive, so it breaks no existing client.

coverageCoverage | null

How much of the addressable set this answer represents. Null means coverage was not measured for this request -- fast and auto do not enumerate -- and never that coverage was zero. Additive, so it breaks no existing client.

auditedbooleandefault: false

Whether the query was checked against the executed filter for dropped requirements. Reported because an empty constraints_unmet only means something if something looked.

constraints_unmetarray of string

Requirements in your query that the search could not express, in your own words. Non-empty means part of the question was not answered -- most often because it needs a dataset this search cannot reach (job postings, employment history, patents, news, funding dates). When this is non-empty, universe_exhausted is withheld: 'we returned everything that matches' cannot be true of a question that was never asked.

criteriaarray of object

Per criterion: evaluated, passed, success_rate, and whether it was *proven* by the query or *judged* by a model. Without this a thin result leaves the caller guessing which requirement thinned it.

enumeratedinteger

How many of them this answer carries. ≥ 0.

enumeration_recallnumber | null

enumerated / universe. Null when the universe was not exact, because a ratio over an estimate is not a recall figure. Note this measures coverage of the *resolved query*, not of the user's intent -- a wrong predicate can be exhaustively enumerated. ≥ 0, ≤ 1.

linkagearray of object

One entry per other dataset this answer joined against: corpus, join_key, observable, of_constrained, ratio, is_lower_bound. ratio is the fraction of your matching accounts that dataset can even see -- measured at 5-60% depending on the dataset and how large the companies are, and never 100%. Non-empty therefore means universe_exhausted is withheld by construction: we returned everything reachable, and a dataset cannot see the rest.

linkage_coveragenumber | null

The joins combined, as a product rather than a minimum: two datasets seeing 27% and 24% of your accounts jointly see about 6.5%, not 24%. Null when no join was performed or when any leg's coverage is unknown.

linkage_coverage_is_lower_boundbooleandefault: false

True when a key set was capped or coverage was estimated rather than measured, making linkage_coverage a floor. Narrowing the question makes it exact.

similarityarray of object

Narrowings done by ranking rather than by predicate. Each entry carries the concept, how many ids it resolved to, the k asked for, whether the list was cut at that ceiling, and the fraction of candidates that could be compared at all. Non-empty means universe_exhausted is withheld on purpose: a cosine is a degree, so a top-k ranking has no complete state, and 2.9% of companies carry no embedding to compare.

truncated_bystring | null

Which limit stopped the enumeration short, when one did.

universeinteger

Records matching the resolved query, counted, not sampled. ≥ 0.

universe_exhaustedbooleandefault: false

Every matching record was returned and the count agrees. The claim an unbounded-corpus search engine cannot make.

universe_is_exactboolean

False when the count hit a cap. Always serialized: a capped count presented as exact is the same lie as an unmeasured one.

degradationarray of Degradation
detailstring
impact"recall" | "precision" | "freshness" | "fields"
reasonDegradationReason

Why an answer is less than it should be. Closed, because a client that cannot branch on the reason can only show the user a shrug. These are the honest constraints — partial vector coverage, smry mapped as keyword so it cannot be scored lexically, a federated corpus being unreachable — surfaced at runtime instead of in a footnote.

source_corpusSourceCorpus | null
has_moreboolean
metaResponseMeta

Present on every 2xx, including the ones that are not paginated.

as_ofstring
credential"api_key" | "session"default: api_key

Which credential produced this response. session means the dashboard playground ran it as the signed-in user rather than as an API key — so it is billed to the user, subject to interactive rate limits, and carries no integration compatibility guarantee. Additive and defaulted, so it breaks no existing client.

credits_chargednumber | null

What this request cost, in credits, to at most three decimals. 0 when it cost nothing: a Basic or AI search that found nothing, rows this search already paid for (a cursor sent again, or a request repeated with the same Idempotency-Key on the same UTC day), or a test key. A request without a cursor or a repeated key is a new search, so keep the first page rather than asking for it again. null on a free endpoint.

environment"live" | "test"

Echoed on every response so a developer can never mistake a test-key result for a live one.

request_idstring
next_cursorstring | null

Opaque and signed. Invariant: has_more == (next_cursor is not None). There is no page or offset parameter — not accepted, not deprecated, never present.

resolved_searchResolvedSearch | null
categoryEntityCategory

*What* to search, and what a returned row is. One parameter carries both, because they are the same fact: a search of patent returns patents. The alternative — a source/vertical selector beside a narrower category — lets a caller ask for patents from the people index, a combination that has no meaning and would need rejecting at runtime. A closed set that cannot express the contradiction is better than a validator that catches it. Values are exactly prism's own row types, so category in the request and results[].category in the response are always the same string. company and person are the GTM index; the rest are separate corpora with their own filters, freshness and coverage. Not everything applies everywhere: see SearchRequest, which rejects the GTM-only parameters rather than ignoring them. job_opening is a document corpus like patent/news_article/etc — a posting, not an entity — but its records carry a domain (the posting company's) all the same. It is deliberately not in GTM_CATEGORIES (that set is about the entity/document distinction, and a job posting is still a document), but it *is* in DOMAIN_FILTERABLE_CATEGORIES, which exists specifically to separate those two axes.

conflictsarray of object
filtersFilters
filters_source"caller" | "parser" | "caller+parser" | "none"default: none
mode"fast" | "auto" | "deep"

How hard to work on the query. The distinction is *what the words mean*, not how many results come back: - fast — match my words. The query is matched by meaning (vector retrieval, falling back to keywords where vectors are unavailable); no LLM in the path, so nothing is extracted into filters. - auto — understand my intent. The parser extracts filters. - deep — reason about it. Multi-step, slowest, most expensive. fast was very nearly defined as "filters only, no LLM", which would have made query — the primary parameter — silently inert. A parameter that does nothing is worse than one that is missing.

overridesarray of object
parser_versionstring
querystring | null
semantic_querystring | null
semantic_scope"company" | "person" | null
sortarray of object
resultsarray of EntityHit[MarketReportRecord]
categoryEntityCategory

*What* to search, and what a returned row is. One parameter carries both, because they are the same fact: a search of patent returns patents. The alternative — a source/vertical selector beside a narrower category — lets a caller ask for patents from the people index, a combination that has no meaning and would need rejecting at runtime. A closed set that cannot express the contradiction is better than a validator that catches it. Values are exactly prism's own row types, so category in the request and results[].category in the response are always the same string. company and person are the GTM index; the rest are separate corpora with their own filters, freshness and coverage. Not everything applies everywhere: see SearchRequest, which rejects the GTM-only parameters rather than ignoring them. job_opening is a document corpus like patent/news_article/etc — a posting, not an entity — but its records carry a domain (the posting company's) all the same. It is deliberately not in GTM_CATEGORIES (that set is about the entity/document distinction, and a job posting is still a document), but it *is* in DOMAIN_FILTERABLE_CATEGORIES, which exists specifically to separate those two axes.

foundboolean
idstring
matchesarray of MarketReportRecord
bodystring | null
body_freestring | null
industrystring | null
published_datestring | null
publisherstring | null
titlestring | null
urlstring | null
suggestionSearchSuggestion | null

A better way to have asked this question -- a different category (kind: search), or agentic search via POST /v1/agents (kind: agentic). Advisory: these results came from the search that was asked for, whatever this says. Null when there is nothing worth suggesting, which is the common case. Additive, so it breaks no existing client.

categoryEntityCategory | null

The category to search instead. Set iff kind is search.

kind"search" | "agentic"

search — a different category fits. agentic — no single search fits; use POST /v1/agents.

messagestring

One ready-to-show sentence.

totalinteger

≥ 0.

total_is_estimateboolean

Always serialized, never defaulted away. A field clients can forget exists is a field that renders an estimate as exact.

Fundings#

With "by": "name" (the default), each value is the name of the company the funding round belongs to, and every round found for it comes back under matches.

curl -X POST "https://api.sproutsdata.ai/v1/entities/fundings" \
  -H "X-API-Key: $SPROUTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "ids": [
         "Stripe"
       ],
       "by": "name"
     }'
by"id" | "name"default: name

How to interpret ids: "name" (default) treats each entry as a free-text name — an article headline, a report title, a job posting's role, or the company a funding round belongs to — and looks it up the way you'd look up a trend by name. "id" treats each entry as a prism id, same as every other category. The id on a search hit is an opaque hash, not a prism id, so it does not resolve here.

fieldsarray of string | null

Restrict the returned fields. Omit for the full record.

idsarray of string, ≥ 1, ≤ 100required

Headers

Idempotency-Keystring

Makes a retry safe. Send a unique value per request and reuse it when you retry that same request: with the same body and credential, on the same UTC day, rows already charged are not charged again.

attributionarray of Attribution
as_ofstring | null
domainstring | null
quotestring | null

RESERVED for per-fact citation. Always null in v1.

source_corpusSourceCorpus

Where content came from. Closed set — it appears in attribution[]. The first four are the GTM entity graph. The rest are the document corpora behind the non-entity categories, each a distinct index with its own refresh cadence — which is the reason they are named separately rather than lumped under one label: attribution[].as_of means nothing if two corpora updated a month apart share a name.

urlstring | null

RESERVED for per-fact citation. Always null in v1.

columnsarray of object | null

The answer table's columns, in order, when a run carries extra columns beyond the entity's own fields -- a job-opening link, a value joined from another dataset. Each entry is {name, description, source}; the value for each sits on every row in results keyed by the column name. Null means a plain entity table. Additive, so it breaks no existing client.

coverageCoverage | null

How much of the addressable set this answer represents. Null means coverage was not measured for this request -- fast and auto do not enumerate -- and never that coverage was zero. Additive, so it breaks no existing client.

auditedbooleandefault: false

Whether the query was checked against the executed filter for dropped requirements. Reported because an empty constraints_unmet only means something if something looked.

constraints_unmetarray of string

Requirements in your query that the search could not express, in your own words. Non-empty means part of the question was not answered -- most often because it needs a dataset this search cannot reach (job postings, employment history, patents, news, funding dates). When this is non-empty, universe_exhausted is withheld: 'we returned everything that matches' cannot be true of a question that was never asked.

criteriaarray of object

Per criterion: evaluated, passed, success_rate, and whether it was *proven* by the query or *judged* by a model. Without this a thin result leaves the caller guessing which requirement thinned it.

enumeratedinteger

How many of them this answer carries. ≥ 0.

enumeration_recallnumber | null

enumerated / universe. Null when the universe was not exact, because a ratio over an estimate is not a recall figure. Note this measures coverage of the *resolved query*, not of the user's intent -- a wrong predicate can be exhaustively enumerated. ≥ 0, ≤ 1.

linkagearray of object

One entry per other dataset this answer joined against: corpus, join_key, observable, of_constrained, ratio, is_lower_bound. ratio is the fraction of your matching accounts that dataset can even see -- measured at 5-60% depending on the dataset and how large the companies are, and never 100%. Non-empty therefore means universe_exhausted is withheld by construction: we returned everything reachable, and a dataset cannot see the rest.

linkage_coveragenumber | null

The joins combined, as a product rather than a minimum: two datasets seeing 27% and 24% of your accounts jointly see about 6.5%, not 24%. Null when no join was performed or when any leg's coverage is unknown.

linkage_coverage_is_lower_boundbooleandefault: false

True when a key set was capped or coverage was estimated rather than measured, making linkage_coverage a floor. Narrowing the question makes it exact.

similarityarray of object

Narrowings done by ranking rather than by predicate. Each entry carries the concept, how many ids it resolved to, the k asked for, whether the list was cut at that ceiling, and the fraction of candidates that could be compared at all. Non-empty means universe_exhausted is withheld on purpose: a cosine is a degree, so a top-k ranking has no complete state, and 2.9% of companies carry no embedding to compare.

truncated_bystring | null

Which limit stopped the enumeration short, when one did.

universeinteger

Records matching the resolved query, counted, not sampled. ≥ 0.

universe_exhaustedbooleandefault: false

Every matching record was returned and the count agrees. The claim an unbounded-corpus search engine cannot make.

universe_is_exactboolean

False when the count hit a cap. Always serialized: a capped count presented as exact is the same lie as an unmeasured one.

degradationarray of Degradation
detailstring
impact"recall" | "precision" | "freshness" | "fields"
reasonDegradationReason

Why an answer is less than it should be. Closed, because a client that cannot branch on the reason can only show the user a shrug. These are the honest constraints — partial vector coverage, smry mapped as keyword so it cannot be scored lexically, a federated corpus being unreachable — surfaced at runtime instead of in a footnote.

source_corpusSourceCorpus | null
has_moreboolean
metaResponseMeta

Present on every 2xx, including the ones that are not paginated.

as_ofstring
credential"api_key" | "session"default: api_key

Which credential produced this response. session means the dashboard playground ran it as the signed-in user rather than as an API key — so it is billed to the user, subject to interactive rate limits, and carries no integration compatibility guarantee. Additive and defaulted, so it breaks no existing client.

credits_chargednumber | null

What this request cost, in credits, to at most three decimals. 0 when it cost nothing: a Basic or AI search that found nothing, rows this search already paid for (a cursor sent again, or a request repeated with the same Idempotency-Key on the same UTC day), or a test key. A request without a cursor or a repeated key is a new search, so keep the first page rather than asking for it again. null on a free endpoint.

environment"live" | "test"

Echoed on every response so a developer can never mistake a test-key result for a live one.

request_idstring
next_cursorstring | null

Opaque and signed. Invariant: has_more == (next_cursor is not None). There is no page or offset parameter — not accepted, not deprecated, never present.

resolved_searchResolvedSearch | null
categoryEntityCategory

*What* to search, and what a returned row is. One parameter carries both, because they are the same fact: a search of patent returns patents. The alternative — a source/vertical selector beside a narrower category — lets a caller ask for patents from the people index, a combination that has no meaning and would need rejecting at runtime. A closed set that cannot express the contradiction is better than a validator that catches it. Values are exactly prism's own row types, so category in the request and results[].category in the response are always the same string. company and person are the GTM index; the rest are separate corpora with their own filters, freshness and coverage. Not everything applies everywhere: see SearchRequest, which rejects the GTM-only parameters rather than ignoring them. job_opening is a document corpus like patent/news_article/etc — a posting, not an entity — but its records carry a domain (the posting company's) all the same. It is deliberately not in GTM_CATEGORIES (that set is about the entity/document distinction, and a job posting is still a document), but it *is* in DOMAIN_FILTERABLE_CATEGORIES, which exists specifically to separate those two axes.

conflictsarray of object
filtersFilters
filters_source"caller" | "parser" | "caller+parser" | "none"default: none
mode"fast" | "auto" | "deep"

How hard to work on the query. The distinction is *what the words mean*, not how many results come back: - fast — match my words. The query is matched by meaning (vector retrieval, falling back to keywords where vectors are unavailable); no LLM in the path, so nothing is extracted into filters. - auto — understand my intent. The parser extracts filters. - deep — reason about it. Multi-step, slowest, most expensive. fast was very nearly defined as "filters only, no LLM", which would have made query — the primary parameter — silently inert. A parameter that does nothing is worse than one that is missing.

overridesarray of object
parser_versionstring
querystring | null
semantic_querystring | null
semantic_scope"company" | "person" | null
sortarray of object
resultsarray of EntityHit[FundingRecord]
categoryEntityCategory

*What* to search, and what a returned row is. One parameter carries both, because they are the same fact: a search of patent returns patents. The alternative — a source/vertical selector beside a narrower category — lets a caller ask for patents from the people index, a combination that has no meaning and would need rejecting at runtime. A closed set that cannot express the contradiction is better than a validator that catches it. Values are exactly prism's own row types, so category in the request and results[].category in the response are always the same string. company and person are the GTM index; the rest are separate corpora with their own filters, freshness and coverage. Not everything applies everywhere: see SearchRequest, which rejects the GTM-only parameters rather than ignoring them. job_opening is a document corpus like patent/news_article/etc — a posting, not an entity — but its records carry a domain (the posting company's) all the same. It is deliberately not in GTM_CATEGORIES (that set is about the entity/document distinction, and a job posting is still a document), but it *is* in DOMAIN_FILTERABLE_CATEGORIES, which exists specifically to separate those two axes.

foundboolean
idstring
matchesarray of FundingRecord
amount_nativeFundingAmountNative | null
amountnumber | null
currencystring | null
amount_usdnumber | null
announced_onstring | null
companyFundingCompany | null
citystring | null
countrystring | null
descriptionstring | null
domainstring | null
employeesinteger | null
foundedstring | null
industrystring | null
namestring | null
stagestring | null
total_fundingnumber | null
company_trendsarray of array of string
funding_round_idstring | null
investorsarray of FundingInvestor
countrystring | null
idstring | null
is_leadboolean | null
namestring | null
round_typestring | null
suggestionSearchSuggestion | null

A better way to have asked this question -- a different category (kind: search), or agentic search via POST /v1/agents (kind: agentic). Advisory: these results came from the search that was asked for, whatever this says. Null when there is nothing worth suggesting, which is the common case. Additive, so it breaks no existing client.

categoryEntityCategory | null

The category to search instead. Set iff kind is search.

kind"search" | "agentic"

search — a different category fits. agentic — no single search fits; use POST /v1/agents.

messagestring

One ready-to-show sentence.

totalinteger

≥ 0.

total_is_estimateboolean

Always serialized, never defaulted away. A field clients can forget exists is a field that renders an estimate as exact.

Job openings#

With "by": "name" (the default), each value is a job role, and the matching postings come back most recent first.

curl -X POST "https://api.sproutsdata.ai/v1/entities/job-openings" \
  -H "X-API-Key: $SPROUTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "ids": [
         "Software Engineer"
       ],
       "by": "name"
     }'
by"id" | "name"default: name

How to interpret ids: "name" (default) treats each entry as a free-text name — an article headline, a report title, a job posting's role, or the company a funding round belongs to — and looks it up the way you'd look up a trend by name. "id" treats each entry as a prism id, same as every other category. The id on a search hit is an opaque hash, not a prism id, so it does not resolve here.

fieldsarray of string | null

Restrict the returned fields. Omit for the full record.

idsarray of string, ≥ 1, ≤ 100required

Headers

Idempotency-Keystring

Makes a retry safe. Send a unique value per request and reuse it when you retry that same request: with the same body and credential, on the same UTC day, rows already charged are not charged again.

attributionarray of Attribution
as_ofstring | null
domainstring | null
quotestring | null

RESERVED for per-fact citation. Always null in v1.

source_corpusSourceCorpus

Where content came from. Closed set — it appears in attribution[]. The first four are the GTM entity graph. The rest are the document corpora behind the non-entity categories, each a distinct index with its own refresh cadence — which is the reason they are named separately rather than lumped under one label: attribution[].as_of means nothing if two corpora updated a month apart share a name.

urlstring | null

RESERVED for per-fact citation. Always null in v1.

columnsarray of object | null

The answer table's columns, in order, when a run carries extra columns beyond the entity's own fields -- a job-opening link, a value joined from another dataset. Each entry is {name, description, source}; the value for each sits on every row in results keyed by the column name. Null means a plain entity table. Additive, so it breaks no existing client.

coverageCoverage | null

How much of the addressable set this answer represents. Null means coverage was not measured for this request -- fast and auto do not enumerate -- and never that coverage was zero. Additive, so it breaks no existing client.

auditedbooleandefault: false

Whether the query was checked against the executed filter for dropped requirements. Reported because an empty constraints_unmet only means something if something looked.

constraints_unmetarray of string

Requirements in your query that the search could not express, in your own words. Non-empty means part of the question was not answered -- most often because it needs a dataset this search cannot reach (job postings, employment history, patents, news, funding dates). When this is non-empty, universe_exhausted is withheld: 'we returned everything that matches' cannot be true of a question that was never asked.

criteriaarray of object

Per criterion: evaluated, passed, success_rate, and whether it was *proven* by the query or *judged* by a model. Without this a thin result leaves the caller guessing which requirement thinned it.

enumeratedinteger

How many of them this answer carries. ≥ 0.

enumeration_recallnumber | null

enumerated / universe. Null when the universe was not exact, because a ratio over an estimate is not a recall figure. Note this measures coverage of the *resolved query*, not of the user's intent -- a wrong predicate can be exhaustively enumerated. ≥ 0, ≤ 1.

linkagearray of object

One entry per other dataset this answer joined against: corpus, join_key, observable, of_constrained, ratio, is_lower_bound. ratio is the fraction of your matching accounts that dataset can even see -- measured at 5-60% depending on the dataset and how large the companies are, and never 100%. Non-empty therefore means universe_exhausted is withheld by construction: we returned everything reachable, and a dataset cannot see the rest.

linkage_coveragenumber | null

The joins combined, as a product rather than a minimum: two datasets seeing 27% and 24% of your accounts jointly see about 6.5%, not 24%. Null when no join was performed or when any leg's coverage is unknown.

linkage_coverage_is_lower_boundbooleandefault: false

True when a key set was capped or coverage was estimated rather than measured, making linkage_coverage a floor. Narrowing the question makes it exact.

similarityarray of object

Narrowings done by ranking rather than by predicate. Each entry carries the concept, how many ids it resolved to, the k asked for, whether the list was cut at that ceiling, and the fraction of candidates that could be compared at all. Non-empty means universe_exhausted is withheld on purpose: a cosine is a degree, so a top-k ranking has no complete state, and 2.9% of companies carry no embedding to compare.

truncated_bystring | null

Which limit stopped the enumeration short, when one did.

universeinteger

Records matching the resolved query, counted, not sampled. ≥ 0.

universe_exhaustedbooleandefault: false

Every matching record was returned and the count agrees. The claim an unbounded-corpus search engine cannot make.

universe_is_exactboolean

False when the count hit a cap. Always serialized: a capped count presented as exact is the same lie as an unmeasured one.

degradationarray of Degradation
detailstring
impact"recall" | "precision" | "freshness" | "fields"
reasonDegradationReason

Why an answer is less than it should be. Closed, because a client that cannot branch on the reason can only show the user a shrug. These are the honest constraints — partial vector coverage, smry mapped as keyword so it cannot be scored lexically, a federated corpus being unreachable — surfaced at runtime instead of in a footnote.

source_corpusSourceCorpus | null
has_moreboolean
metaResponseMeta

Present on every 2xx, including the ones that are not paginated.

as_ofstring
credential"api_key" | "session"default: api_key

Which credential produced this response. session means the dashboard playground ran it as the signed-in user rather than as an API key — so it is billed to the user, subject to interactive rate limits, and carries no integration compatibility guarantee. Additive and defaulted, so it breaks no existing client.

credits_chargednumber | null

What this request cost, in credits, to at most three decimals. 0 when it cost nothing: a Basic or AI search that found nothing, rows this search already paid for (a cursor sent again, or a request repeated with the same Idempotency-Key on the same UTC day), or a test key. A request without a cursor or a repeated key is a new search, so keep the first page rather than asking for it again. null on a free endpoint.

environment"live" | "test"

Echoed on every response so a developer can never mistake a test-key result for a live one.

request_idstring
next_cursorstring | null

Opaque and signed. Invariant: has_more == (next_cursor is not None). There is no page or offset parameter — not accepted, not deprecated, never present.

resolved_searchResolvedSearch | null
categoryEntityCategory

*What* to search, and what a returned row is. One parameter carries both, because they are the same fact: a search of patent returns patents. The alternative — a source/vertical selector beside a narrower category — lets a caller ask for patents from the people index, a combination that has no meaning and would need rejecting at runtime. A closed set that cannot express the contradiction is better than a validator that catches it. Values are exactly prism's own row types, so category in the request and results[].category in the response are always the same string. company and person are the GTM index; the rest are separate corpora with their own filters, freshness and coverage. Not everything applies everywhere: see SearchRequest, which rejects the GTM-only parameters rather than ignoring them. job_opening is a document corpus like patent/news_article/etc — a posting, not an entity — but its records carry a domain (the posting company's) all the same. It is deliberately not in GTM_CATEGORIES (that set is about the entity/document distinction, and a job posting is still a document), but it *is* in DOMAIN_FILTERABLE_CATEGORIES, which exists specifically to separate those two axes.

conflictsarray of object
filtersFilters
filters_source"caller" | "parser" | "caller+parser" | "none"default: none
mode"fast" | "auto" | "deep"

How hard to work on the query. The distinction is *what the words mean*, not how many results come back: - fast — match my words. The query is matched by meaning (vector retrieval, falling back to keywords where vectors are unavailable); no LLM in the path, so nothing is extracted into filters. - auto — understand my intent. The parser extracts filters. - deep — reason about it. Multi-step, slowest, most expensive. fast was very nearly defined as "filters only, no LLM", which would have made query — the primary parameter — silently inert. A parameter that does nothing is worse than one that is missing.

overridesarray of object
parser_versionstring
querystring | null
semantic_querystring | null
semantic_scope"company" | "person" | null
sortarray of object
resultsarray of EntityHit[JobOpeningRecord]
categoryEntityCategory

*What* to search, and what a returned row is. One parameter carries both, because they are the same fact: a search of patent returns patents. The alternative — a source/vertical selector beside a narrower category — lets a caller ask for patents from the people index, a combination that has no meaning and would need rejecting at runtime. A closed set that cannot express the contradiction is better than a validator that catches it. Values are exactly prism's own row types, so category in the request and results[].category in the response are always the same string. company and person are the GTM index; the rest are separate corpora with their own filters, freshness and coverage. Not everything applies everywhere: see SearchRequest, which rejects the GTM-only parameters rather than ignoring them. job_opening is a document corpus like patent/news_article/etc — a posting, not an entity — but its records carry a domain (the posting company's) all the same. It is deliberately not in GTM_CATEGORIES (that set is about the entity/document distinction, and a job posting is still a document), but it *is* in DOMAIN_FILTERABLE_CATEGORIES, which exists specifically to separate those two axes.

foundboolean
idstring
matchesarray of JobOpeningRecord
companyJobCompany
domainstring | null
idstring | null
li_urlstring | null
namestring | null
departmentJobDepartment
departmentstring | null
sub_departmentstring | null
descriptionstring | null
employment_typearray of string
job_idstring | null
last_modified_atstring | null
locationJobLocation
citystring | null
countryarray of string
statestring | null
street_addressstring | null
posted_atstring | null
salaryJobSalary | null
as_reportedstring | null
currencystring | null
highnumber | null
lownumber | null
senioritystring | null
titlestring | null
urlstring | null
work_arrangementJobWorkArrangement
hybridbooleandefault: false
remotebooleandefault: false
suggestionSearchSuggestion | null

A better way to have asked this question -- a different category (kind: search), or agentic search via POST /v1/agents (kind: agentic). Advisory: these results came from the search that was asked for, whatever this says. Null when there is nothing worth suggesting, which is the common case. Additive, so it breaks no existing client.

categoryEntityCategory | null

The category to search instead. Set iff kind is search.

kind"search" | "agentic"

search — a different category fits. agentic — no single search fits; use POST /v1/agents.

messagestring

One ready-to-show sentence.

totalinteger

≥ 0.

total_is_estimateboolean

Always serialized, never defaulted away. A field clients can forget exists is a field that renders an estimate as exact.

Errors#

All seven routes answer the same set:

StatusCodeSummary
401auth.unauthorizedNo usable credential (cause deliberately unspecified)
402credits.insufficientThe allocation cannot fund this action
403auth.browser_originA secret key was used from a browser
403auth.insufficient_scopeThe credential does not hold the required scope
422pagination.cursor_invalidThe cursor could not be read (e.g. a filter changed mid-pagination)
422request.invalidA field failed validation (extra.errors has the detail)
429quota.burst_exceededInteractive burst limit hit — wait Retry-After seconds
503credits.unavailableThe billing service could not confirm the charge; retry with the same Idempotency-Key
503upstream.unavailableThe retrieval engine is unreachable (not charged)
504upstream.timeoutThe retrieval engine did not answer in time (not charged)