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.
/v1/entities/patentsLook 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:
| Route | ids are | by |
|---|---|---|
/v1/entities/patents (this one) | Patent numbers | Not accepted |
/v1/entities/trends | Trend names | Not accepted |
/v1/entities/academic-reports | DOIs | Not accepted |
/v1/entities/news | Headlines, or internal ids | name (default) or id |
/v1/entities/market-reports | Report titles, or internal ids | name (default) or id |
/v1/entities/fundings | The company a round belongs to, or internal ids | name (default) or id |
/v1/entities/job-openings | Job roles, or internal ids | name (default) or id |
All seven need dsp.entities.read.
What the seven routes share#
Request
| Field | Notes |
|---|---|
ids | Required. 1 to 100 values per request, or 1 to 50 when by is name |
fields | Optional 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) |
by | Only 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 inmatches, or none for a miss. - A name lookup (
"by": "name") keeps every candidate, somatchescan 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 | nullRestrict the returned fields. Omit for the full record.
idsarray of string, ≥ 1, ≤ 100requiredHeaders
Idempotency-KeystringMakes 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 Attributionas_ofstring | nulldomainstring | nullquotestring | nullRESERVED for per-fact citation. Always null in v1.
source_corpusSourceCorpusWhere 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 | nullRESERVED for per-fact citation. Always null in v1.
columnsarray of object | nullThe 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 | nullHow 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: falseWhether 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 stringRequirements 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 objectPer 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.
enumeratedintegerHow many of them this answer carries. ≥ 0.
enumeration_recallnumber | nullenumerated / 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 objectOne 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 | nullThe 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: falseTrue 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 objectNarrowings 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 | nullWhich limit stopped the enumeration short, when one did.
universeintegerRecords matching the resolved query, counted, not sampled. ≥ 0.
universe_exhaustedbooleandefault: falseEvery matching record was returned and the count agrees. The claim an unbounded-corpus search engine cannot make.
universe_is_exactbooleanFalse when the count hit a cap. Always serialized: a capped count presented as exact is the same lie as an unmeasured one.
degradationarray of Degradationdetailstringimpact"recall" | "precision" | "freshness" | "fields"reasonDegradationReasonWhy 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 | nullhas_morebooleanmetaResponseMetaPresent on every 2xx, including the ones that are not paginated.
as_ofstringcredential"api_key" | "session"default: api_keyWhich 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 | nullWhat 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_idstringnext_cursorstring | nullOpaque 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 | nullcategoryEntityCategory*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 objectfiltersFiltersfilters_source"caller" | "parser" | "caller+parser" | "none"default: nonemode"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 objectparser_versionstringquerystring | nullsemantic_querystring | nullsemantic_scope"company" | "person" | nullsortarray of objectresultsarray 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.
foundbooleanidstringmatchesarray of PatentRecordabstractstring | nullapplicantsarray of PatentApplicantcompany_connectionPatentCompanyConnection | nullcompany_idstring | nullcountryPatentCountry | nullcodestring | nullnamestring | nullnamestring | nullapplicationPatentApplication | nullfiledstring | nullkind_codestring | nullnumberstring | nullofficestring | nulloffice_namestring | nulltypestring | nullclassificationarray of stringclassification_detailarray of PatentClassificationDetailcodestring | nulldefinitionstring | nullcreated_atstring | nullfamily_numberstring | nullgranted_datestring | nullinventorsarray of PatentInventornamestring | nullpatent_idstring | nullpriorityarray of PatentPriorityFilingdatestring | nullnumberstring | nullpublicationsarray of PatentPublicationdatestring | nullgrantedstring | nullkind_codestring | nullnumberstring | nullstatusstring | nullstatus"granted" | "applied" | "unknown" | nulltagsarray of stringtitlestring | nullsuggestionSearchSuggestion | nullA 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 | nullThe 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.
messagestringOne ready-to-show sentence.
totalinteger≥ 0.
total_is_estimatebooleanAlways serialized, never defaulted away. A field clients can forget exists is a field that renders an estimate as exact.
Trends#
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 | nullRestrict the returned fields. Omit for the full record.
idsarray of string, ≥ 1, ≤ 100requiredHeaders
Idempotency-KeystringMakes 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 Attributionas_ofstring | nulldomainstring | nullquotestring | nullRESERVED for per-fact citation. Always null in v1.
source_corpusSourceCorpusWhere 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 | nullRESERVED for per-fact citation. Always null in v1.
columnsarray of object | nullThe 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 | nullHow 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: falseWhether 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 stringRequirements 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 objectPer 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.
enumeratedintegerHow many of them this answer carries. ≥ 0.
enumeration_recallnumber | nullenumerated / 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 objectOne 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 | nullThe 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: falseTrue 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 objectNarrowings 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 | nullWhich limit stopped the enumeration short, when one did.
universeintegerRecords matching the resolved query, counted, not sampled. ≥ 0.
universe_exhaustedbooleandefault: falseEvery matching record was returned and the count agrees. The claim an unbounded-corpus search engine cannot make.
universe_is_exactbooleanFalse when the count hit a cap. Always serialized: a capped count presented as exact is the same lie as an unmeasured one.
degradationarray of Degradationdetailstringimpact"recall" | "precision" | "freshness" | "fields"reasonDegradationReasonWhy 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 | nullhas_morebooleanmetaResponseMetaPresent on every 2xx, including the ones that are not paginated.
as_ofstringcredential"api_key" | "session"default: api_keyWhich 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 | nullWhat 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_idstringnext_cursorstring | nullOpaque 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 | nullcategoryEntityCategory*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 objectfiltersFiltersfilters_source"caller" | "parser" | "caller+parser" | "none"default: nonemode"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 objectparser_versionstringquerystring | nullsemantic_querystring | nullsemantic_scope"company" | "person" | nullsortarray of objectresultsarray 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.
foundbooleanidstringmatchesarray of TrendRecordbadgesTrendBadges | nullfifteen_percentarray of stringfive_percentarray of stringten_percentarray of stringbiggest_investorsarray of TrendInvestorcompanies_invested_inarray of TrendInvestorCompanyinvested_sumnumber | nullnamestring | nullinvestednumber | nullnamestring | nullroundsinteger | nullconnectionsarray of TrendConnectionoverlapnumber | nullshared_companiesinteger | nulltrendstring | nullcountriesarray of stringcreated_atstring | nulldescriptionTrendDescription | nulllongstring | nullshortstring | nulldistributionsTrendDistributions | nullemployee_growthTrendDistribution | nullboxplotTrendBoxplot | nullmaximumnumber | nullmediannumber | nullminimumnumber | nullquartilesarray of TrendQuartilestdnumber | nulltop_companiesarray of TrendNamedTotalvariancenumber | nullfundingTrendDistribution | nullboxplotTrendBoxplot | nullmaximumnumber | nullmediannumber | nullminimumnumber | nullquartilesarray of TrendQuartilestdnumber | nulltop_companiesarray of TrendNamedTotalvariancenumber | nullmanpowerTrendDistribution | nullboxplotTrendBoxplot | nullmaximumnumber | nullmediannumber | nullminimumnumber | nullquartilesarray of TrendQuartilestdnumber | nulltop_companiesarray of TrendNamedTotalvariancenumber | nullrevenueTrendDistribution | nullboxplotTrendBoxplot | nullmaximumnumber | nullmediannumber | nullminimumnumber | nullquartilesarray of TrendQuartilestdnumber | nulltop_companiesarray of TrendNamedTotalvariancenumber | nullfeaturesTrendFeatures | nullacademic_activitiesarray of TrendFeaturenamestring | nullsizestring | nullsize_cleanednumber | nullsourcearray of stringacquisitionsarray of TrendDealamountnumber | nullbuyersarray of TrendCompanyRefcompaniesarray of TrendCompanyRefdatestring | nullinvestorsarray of TrendCompanyRefprojectstring | nullrecipientsarray of TrendCompanyRefsharestring | nullshare_percentagenumber | nullsourcearray of stringtargetsarray of TrendCompanyRefapplication_areasarray of TrendFeaturenamestring | nullsizestring | nullsize_cleanednumber | nullsourcearray of stringbranding_and_messagingarray of stringbusiness_classificationarray of stringbusiness_modelsarray of stringcommunity_engagementarray of TrendFeaturenamestring | nullsizestring | nullsize_cleanednumber | nullsourcearray of stringcore_technologiesarray of TrendFeaturenamestring | nullsizestring | nullsize_cleanednumber | nullsourcearray of stringcustomer_relationship_focusarray of TrendFeaturenamestring | nullsizestring | nullsize_cleanednumber | nullsourcearray of stringcustomer_segmentsarray of TrendFeaturenamestring | nullsizestring | nullsize_cleanednumber | nullsourcearray of stringeducation_and_trainingarray of TrendFeaturenamestring | nullsizestring | nullsize_cleanednumber | nullsourcearray of stringgovernment_initiativesarray of TrendFeaturenamestring | nullsizestring | nullsize_cleanednumber | nullsourcearray of stringindustry_eventsarray of TrendFeaturenamestring | nullsizestring | nullsize_cleanednumber | nullsourcearray of stringinvestments_and_rndarray of TrendDealamountnumber | nullbuyersarray of TrendCompanyRefcompaniesarray of TrendCompanyRefdatestring | nullinvestorsarray of TrendCompanyRefprojectstring | nullrecipientsarray of TrendCompanyRefsharestring | nullshare_percentagenumber | nullsourcearray of stringtargetsarray of TrendCompanyRefmarket_challengesarray of TrendFeaturenamestring | nullsizestring | nullsize_cleanednumber | nullsourcearray of stringmarket_concentrationarray of TrendDealamountnumber | nullbuyersarray of TrendCompanyRefcompaniesarray of TrendCompanyRefdatestring | nullinvestorsarray of TrendCompanyRefprojectstring | nullrecipientsarray of TrendCompanyRefsharestring | nullshare_percentagenumber | nullsourcearray of stringtargetsarray of TrendCompanyRefmarket_driversarray of TrendFeaturenamestring | nullsizestring | nullsize_cleanednumber | nullsourcearray of stringmarket_segmentsarray of TrendFeaturenamestring | nullsizestring | nullsize_cleanednumber | nullsourcearray of stringpartnerships_and_alliancesarray of TrendDealamountnumber | nullbuyersarray of TrendCompanyRefcompaniesarray of TrendCompanyRefdatestring | nullinvestorsarray of TrendCompanyRefprojectstring | nullrecipientsarray of TrendCompanyRefsharestring | nullshare_percentagenumber | nullsourcearray of stringtargetsarray of TrendCompanyRefregulatory_challengesarray of TrendFeaturenamestring | nullsizestring | nullsize_cleanednumber | nullsourcearray of stringstandards_and_certificationsarray of TrendFeaturenamestring | nullsizestring | nullsize_cleanednumber | nullsourcearray of stringtechnology_limitationsarray of TrendFeaturenamestring | nullsizestring | nullsize_cleanednumber | nullsourcearray of stringtrends_and_insightsarray of TrendFeaturenamestring | nullsizestring | nullsize_cleanednumber | nullsourcearray of stringunique_value_propositionarray of TrendFeaturenamestring | nullsizestring | nullsize_cleanednumber | nullsourcearray of stringgraphsTrendGraphs | nullarticle_startup_global_searcharray of TrendGraphPointdatestring | nullrelative_frequencynumber | nullfunding_raisedarray of TrendGraphPointdatestring | nullrelative_frequencynumber | nullglobal_searcharray of TrendGraphPointdatestring | nullrelative_frequencynumber | nullnew_companiesarray of TrendGraphPointdatestring | nullrelative_frequencynumber | nullnews_coveragearray of TrendGraphPointdatestring | nullrelative_frequencynumber | nullpatents_applicationarray of TrendGraphPointdatestring | nullrelative_frequencynumber | nullpatents_publicationarray of TrendGraphPointdatestring | nullrelative_frequencynumber | nullhighlightsarray of objectindustriesarray of stringmarketTrendMarket | nullcagrTrendMarketCagr | nullpercentnumber | nullsourcearray of stringvaluestring | nullforecastTrendMarketSize | nullamountnumber | nullsourcearray of stringyearstring | nullsizeTrendMarketSize | nullamountnumber | nullsourcearray of stringyearstring | nullpatent_statsTrendPatentStats | nullall_applicantsTrendMetric | nullpercentilenumber | nullrankinteger | nullvaluenumber | nullall_classificationsTrendMetric | nullpercentilenumber | nullrankinteger | nullvaluenumber | nullall_patentsTrendMetric | nullpercentilenumber | nullrankinteger | nullvaluenumber | nullapplications_growthnumber | nullapplications_growth_in_periodnumber | nullgrowth_categorystring | nullmagnitudeTrendMetric | nullpercentilenumber | nullrankinteger | nullvaluenumber | nullmedian_patent_ageTrendMetric | nullpercentilenumber | nullrankinteger | nullvaluenumber | nullpublication_growthnumber | nullpublication_growth_in_periodnumber | nulltop_applicantstring | nulltop_inventorstring | nulltop_issuerstring | nullyearly_growthTrendMetric | nullpercentilenumber | nullrankinteger | nullvaluenumber | nullpublicationsarray of TrendCategoryCountcountinteger | nullnamestring | nullrelation_scorenumber | nullscaleTrendScale | nullarticle_coverageTrendMetric | nullpercentilenumber | nullrankinteger | nullvaluenumber | nullcompaniesinteger | nullemployee_growthTrendTotalAverage | nullaveragenumber | nullrank_percentilenumber | nulltotalnumber | nullfundingTrendFunding | nullaveragenumber | nullaverage_per_roundnumber | nullrank_percentilenumber | nullroundsinteger | nullrounds_percentilenumber | nulltotalnumber | nullunique_investorsinteger | nullmanpowerTrendTotalAverage | nullaveragenumber | nullrank_percentilenumber | nulltotalnumber | nullpatentsTrendTotalAverage | nullaveragenumber | nullrank_percentilenumber | nulltotalnumber | nullrevenueTrendTotalAverage | nullaveragenumber | nullrank_percentilenumber | nulltotalnumber | nullsearch_interestTrendSearchInterest | nullarticle_startup_growthnumber | nullarticle_startup_growth_in_periodnumber | nullarticle_startup_growth_in_period_categorystring | nullaverage_volumeTrendMetric | nullpercentilenumber | nullrankinteger | nullvaluenumber | nullgrowthnumber | nullgrowth_categorystring | nullgrowth_in_periodnumber | nullhype_strengthstring | nullmagnitudeTrendMetric | nullpercentilenumber | nullrankinteger | nullvaluenumber | nulltechnology_adoption_valuenumber | nulltrendingnumber | nulltrending_categorystring | nullyearly_growthTrendMetric | nullpercentilenumber | nullrankinteger | nullvaluenumber | nullsignalsTrendSignals | nullarticle_ageTrendMetric | nullpercentilenumber | nullrankinteger | nullvaluenumber | nullcompany_ageTrendMetric | nullpercentilenumber | nullrankinteger | nullvaluenumber | nullcompany_magnitudeTrendMetric | nullpercentilenumber | nullrankinteger | nullvaluenumber | nullgrowthTrendGrowth | nullannualizedTrendGrowthAnnualized | nullover_windowTrendGrowthOverWindow | nullhypenumber | nullmagnitudeTrendBand | nullcategorystring | nullpercentilenumber | nullvaluenumber | nullmaturityTrendBand | nullcategorystring | nullpercentilenumber | nullvaluenumber | nullnews_magnitudeTrendMetric | nullpercentilenumber | nullrankinteger | nullvaluenumber | nullsignal_strengthstring | nulltechnology_adoptionstring | nulltrend_ageTrendAgeMetric | nullcategorystring | nullpercentilenumber | nullrankinteger | nullvaluenumber | nullsimilar_tagsarray of TrendSimilarTagcountinteger | nullnamestring | nullrelation_scorenumber | nullrelative_percentagenumber | nullsnapshotTrendSnapshot | nullaverage_invested_sum_per_investornumber | nullcompanies_growth_categorystring | nullcompany_maturityTrendCompanyMaturity | nullcategorystring | nullvaluenumber | nullfunding_growth_in_periodnumber | nullfunding_roundsarray of TrendCategoryCountcountinteger | nullnamestring | nullrelation_scorenumber | nullgrantsTrendTotalAverage | nullaveragenumber | nullrank_percentilenumber | nulltotalnumber | nullgrowth_periodnumber | nullinvested_companiesTrendInvestedCompanies | nullpercentage_availablenumber | nulltotal_availabilitynumber | nullinvestment_rounds_per_investornumber | nullmost_common_company_stageTrendCategoryCount | nullcountinteger | nullnamestring | nullrelation_scorenumber | nullmost_frequently_mentioned_companiesarray of stringnews_frequencynumber | nullnews_growth_categorystring | nullspreadTrendMetric | nullpercentilenumber | nullrankinteger | nullvaluenumber | nullyoungest_articlesarray of TrendYoungestArticlearticle_datestring | nullarticle_linkstring | nullarticle_namestring | nullyoungest_companiesarray of TrendYoungestCompanycompany_datestring | nullcompany_idstring | nullstartupsarray of TrendStartupdomainstring | nullscorenumber | nullsummaryTrendSummary | nullcompanies_involvedstring | nullconcise_descriptionstring | nullconclusion_and_key_takeawaysstring | nullgrowth_evaluationstring | nullintroductionstring | nullinvestment_and_fundingstring | nullkey_topics_and_trendsstring | nullmarket_overviewstring | nullnews_and_media_coveragestring | nulltechnology_usedstring | nulltopic_analysisstring | nulltopic_typestring | nulltrendstring | nullsuggestionSearchSuggestion | nullA 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 | nullThe 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.
messagestringOne ready-to-show sentence.
totalinteger≥ 0.
total_is_estimatebooleanAlways 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 | nullRestrict the returned fields. Omit for the full record.
idsarray of string, ≥ 1, ≤ 100requiredHeaders
Idempotency-KeystringMakes 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 Attributionas_ofstring | nulldomainstring | nullquotestring | nullRESERVED for per-fact citation. Always null in v1.
source_corpusSourceCorpusWhere 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 | nullRESERVED for per-fact citation. Always null in v1.
columnsarray of object | nullThe 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 | nullHow 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: falseWhether 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 stringRequirements 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 objectPer 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.
enumeratedintegerHow many of them this answer carries. ≥ 0.
enumeration_recallnumber | nullenumerated / 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 objectOne 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 | nullThe 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: falseTrue 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 objectNarrowings 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 | nullWhich limit stopped the enumeration short, when one did.
universeintegerRecords matching the resolved query, counted, not sampled. ≥ 0.
universe_exhaustedbooleandefault: falseEvery matching record was returned and the count agrees. The claim an unbounded-corpus search engine cannot make.
universe_is_exactbooleanFalse when the count hit a cap. Always serialized: a capped count presented as exact is the same lie as an unmeasured one.
degradationarray of Degradationdetailstringimpact"recall" | "precision" | "freshness" | "fields"reasonDegradationReasonWhy 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 | nullhas_morebooleanmetaResponseMetaPresent on every 2xx, including the ones that are not paginated.
as_ofstringcredential"api_key" | "session"default: api_keyWhich 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 | nullWhat 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_idstringnext_cursorstring | nullOpaque 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 | nullcategoryEntityCategory*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 objectfiltersFiltersfilters_source"caller" | "parser" | "caller+parser" | "none"default: nonemode"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 objectparser_versionstringquerystring | nullsemantic_querystring | nullsemantic_scope"company" | "person" | nullsortarray of objectresultsarray 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.
foundbooleanidstringmatchesarray of AcademicReportRecordabstractstring | nullauthorsarray of AcademicAuthoremploymentstring | nullnamestring | nullcitation_countsAcademicCitationCounts | nullcitationsinteger | nullreferencesinteger | nullcitationsarray of AcademicCitationdatestring | nulldoistring | nulltitlestring | nulldoistring | nullfull_textstring | nullfunded_byarray of stringpaper_typestring | nullpublished_datestring | nullpublisherstring | nullreferencesarray of AcademicReferencedatestring | nulldoistring | nulltitlestring | nulltagsarray of stringtitlestring | nullurlsarray of stringsuggestionSearchSuggestion | nullA 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 | nullThe 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.
messagestringOne ready-to-show sentence.
totalinteger≥ 0.
total_is_estimatebooleanAlways 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: nameHow 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 | nullRestrict the returned fields. Omit for the full record.
idsarray of string, ≥ 1, ≤ 100requiredHeaders
Idempotency-KeystringMakes 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 Attributionas_ofstring | nulldomainstring | nullquotestring | nullRESERVED for per-fact citation. Always null in v1.
source_corpusSourceCorpusWhere 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 | nullRESERVED for per-fact citation. Always null in v1.
columnsarray of object | nullThe 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 | nullHow 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: falseWhether 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 stringRequirements 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 objectPer 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.
enumeratedintegerHow many of them this answer carries. ≥ 0.
enumeration_recallnumber | nullenumerated / 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 objectOne 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 | nullThe 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: falseTrue 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 objectNarrowings 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 | nullWhich limit stopped the enumeration short, when one did.
universeintegerRecords matching the resolved query, counted, not sampled. ≥ 0.
universe_exhaustedbooleandefault: falseEvery matching record was returned and the count agrees. The claim an unbounded-corpus search engine cannot make.
universe_is_exactbooleanFalse when the count hit a cap. Always serialized: a capped count presented as exact is the same lie as an unmeasured one.
degradationarray of Degradationdetailstringimpact"recall" | "precision" | "freshness" | "fields"reasonDegradationReasonWhy 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 | nullhas_morebooleanmetaResponseMetaPresent on every 2xx, including the ones that are not paginated.
as_ofstringcredential"api_key" | "session"default: api_keyWhich 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 | nullWhat 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_idstringnext_cursorstring | nullOpaque 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 | nullcategoryEntityCategory*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 objectfiltersFiltersfilters_source"caller" | "parser" | "caller+parser" | "none"default: nonemode"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 objectparser_versionstringquerystring | nullsemantic_querystring | nullsemantic_scope"company" | "person" | nullsortarray of objectresultsarray 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.
foundbooleanidstringmatchesarray of NewsRecordauthorstring | nullcompaniesNewsCompanyLinks | nulldirect_linkarray of NewsCompanyRefdomainstring | nullnamestring | nulllinkedarray of NewsCompanyRefdomainstring | nullnamestring | nullcontentstring | nulllanguagestring | nulllinkstring | nullplacesNewsPlaces | nullcitiesarray of stringcountriesarray of stringproductsarray of stringpublicationNewsPublication | nulldomainstring | nulllinkstring | nullpopularity_rankstring | nulltitlestring | nullpublished_atstring | nullsummarystring | nulltagsarray of stringtitlestring | nullupdated_atstring | nullsuggestionSearchSuggestion | nullA 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 | nullThe 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.
messagestringOne ready-to-show sentence.
totalinteger≥ 0.
total_is_estimatebooleanAlways 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: nameHow 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 | nullRestrict the returned fields. Omit for the full record.
idsarray of string, ≥ 1, ≤ 100requiredHeaders
Idempotency-KeystringMakes 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 Attributionas_ofstring | nulldomainstring | nullquotestring | nullRESERVED for per-fact citation. Always null in v1.
source_corpusSourceCorpusWhere 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 | nullRESERVED for per-fact citation. Always null in v1.
columnsarray of object | nullThe 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 | nullHow 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: falseWhether 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 stringRequirements 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 objectPer 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.
enumeratedintegerHow many of them this answer carries. ≥ 0.
enumeration_recallnumber | nullenumerated / 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 objectOne 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 | nullThe 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: falseTrue 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 objectNarrowings 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 | nullWhich limit stopped the enumeration short, when one did.
universeintegerRecords matching the resolved query, counted, not sampled. ≥ 0.
universe_exhaustedbooleandefault: falseEvery matching record was returned and the count agrees. The claim an unbounded-corpus search engine cannot make.
universe_is_exactbooleanFalse when the count hit a cap. Always serialized: a capped count presented as exact is the same lie as an unmeasured one.
degradationarray of Degradationdetailstringimpact"recall" | "precision" | "freshness" | "fields"reasonDegradationReasonWhy 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 | nullhas_morebooleanmetaResponseMetaPresent on every 2xx, including the ones that are not paginated.
as_ofstringcredential"api_key" | "session"default: api_keyWhich 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 | nullWhat 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_idstringnext_cursorstring | nullOpaque 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 | nullcategoryEntityCategory*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 objectfiltersFiltersfilters_source"caller" | "parser" | "caller+parser" | "none"default: nonemode"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 objectparser_versionstringquerystring | nullsemantic_querystring | nullsemantic_scope"company" | "person" | nullsortarray of objectresultsarray 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.
foundbooleanidstringmatchesarray of MarketReportRecordbodystring | nullbody_freestring | nullindustrystring | nullpublished_datestring | nullpublisherstring | nulltitlestring | nullurlstring | nullsuggestionSearchSuggestion | nullA 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 | nullThe 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.
messagestringOne ready-to-show sentence.
totalinteger≥ 0.
total_is_estimatebooleanAlways 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: nameHow 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 | nullRestrict the returned fields. Omit for the full record.
idsarray of string, ≥ 1, ≤ 100requiredHeaders
Idempotency-KeystringMakes 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 Attributionas_ofstring | nulldomainstring | nullquotestring | nullRESERVED for per-fact citation. Always null in v1.
source_corpusSourceCorpusWhere 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 | nullRESERVED for per-fact citation. Always null in v1.
columnsarray of object | nullThe 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 | nullHow 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: falseWhether 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 stringRequirements 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 objectPer 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.
enumeratedintegerHow many of them this answer carries. ≥ 0.
enumeration_recallnumber | nullenumerated / 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 objectOne 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 | nullThe 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: falseTrue 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 objectNarrowings 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 | nullWhich limit stopped the enumeration short, when one did.
universeintegerRecords matching the resolved query, counted, not sampled. ≥ 0.
universe_exhaustedbooleandefault: falseEvery matching record was returned and the count agrees. The claim an unbounded-corpus search engine cannot make.
universe_is_exactbooleanFalse when the count hit a cap. Always serialized: a capped count presented as exact is the same lie as an unmeasured one.
degradationarray of Degradationdetailstringimpact"recall" | "precision" | "freshness" | "fields"reasonDegradationReasonWhy 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 | nullhas_morebooleanmetaResponseMetaPresent on every 2xx, including the ones that are not paginated.
as_ofstringcredential"api_key" | "session"default: api_keyWhich 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 | nullWhat 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_idstringnext_cursorstring | nullOpaque 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 | nullcategoryEntityCategory*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 objectfiltersFiltersfilters_source"caller" | "parser" | "caller+parser" | "none"default: nonemode"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 objectparser_versionstringquerystring | nullsemantic_querystring | nullsemantic_scope"company" | "person" | nullsortarray of objectresultsarray 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.
foundbooleanidstringmatchesarray of FundingRecordamount_nativeFundingAmountNative | nullamountnumber | nullcurrencystring | nullamount_usdnumber | nullannounced_onstring | nullcompanyFundingCompany | nullcitystring | nullcountrystring | nulldescriptionstring | nulldomainstring | nullemployeesinteger | nullfoundedstring | nullindustrystring | nullnamestring | nullstagestring | nulltotal_fundingnumber | nullcompany_trendsarray of array of stringfunding_round_idstring | nullinvestorsarray of FundingInvestorcountrystring | nullidstring | nullis_leadboolean | nullnamestring | nullround_typestring | nullsuggestionSearchSuggestion | nullA 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 | nullThe 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.
messagestringOne ready-to-show sentence.
totalinteger≥ 0.
total_is_estimatebooleanAlways 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: nameHow 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 | nullRestrict the returned fields. Omit for the full record.
idsarray of string, ≥ 1, ≤ 100requiredHeaders
Idempotency-KeystringMakes 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 Attributionas_ofstring | nulldomainstring | nullquotestring | nullRESERVED for per-fact citation. Always null in v1.
source_corpusSourceCorpusWhere 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 | nullRESERVED for per-fact citation. Always null in v1.
columnsarray of object | nullThe 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 | nullHow 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: falseWhether 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 stringRequirements 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 objectPer 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.
enumeratedintegerHow many of them this answer carries. ≥ 0.
enumeration_recallnumber | nullenumerated / 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 objectOne 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 | nullThe 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: falseTrue 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 objectNarrowings 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 | nullWhich limit stopped the enumeration short, when one did.
universeintegerRecords matching the resolved query, counted, not sampled. ≥ 0.
universe_exhaustedbooleandefault: falseEvery matching record was returned and the count agrees. The claim an unbounded-corpus search engine cannot make.
universe_is_exactbooleanFalse when the count hit a cap. Always serialized: a capped count presented as exact is the same lie as an unmeasured one.
degradationarray of Degradationdetailstringimpact"recall" | "precision" | "freshness" | "fields"reasonDegradationReasonWhy 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 | nullhas_morebooleanmetaResponseMetaPresent on every 2xx, including the ones that are not paginated.
as_ofstringcredential"api_key" | "session"default: api_keyWhich 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 | nullWhat 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_idstringnext_cursorstring | nullOpaque 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 | nullcategoryEntityCategory*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 objectfiltersFiltersfilters_source"caller" | "parser" | "caller+parser" | "none"default: nonemode"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 objectparser_versionstringquerystring | nullsemantic_querystring | nullsemantic_scope"company" | "person" | nullsortarray of objectresultsarray 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.
foundbooleanidstringmatchesarray of JobOpeningRecordcompanyJobCompanydomainstring | nullidstring | nullli_urlstring | nullnamestring | nulldepartmentJobDepartmentdepartmentstring | nullsub_departmentstring | nulldescriptionstring | nullemployment_typearray of stringjob_idstring | nulllast_modified_atstring | nulllocationJobLocationcitystring | nullcountryarray of stringstatestring | nullstreet_addressstring | nullposted_atstring | nullsalaryJobSalary | nullas_reportedstring | nullcurrencystring | nullhighnumber | nulllownumber | nullsenioritystring | nulltitlestring | nullurlstring | nullwork_arrangementJobWorkArrangementhybridbooleandefault: falseremotebooleandefault: falsesuggestionSearchSuggestion | nullA 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 | nullThe 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.
messagestringOne ready-to-show sentence.
totalinteger≥ 0.
total_is_estimatebooleanAlways 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:
| Status | Code | Summary |
|---|---|---|
| 401 | auth.unauthorized | No usable credential (cause deliberately unspecified) |
| 402 | credits.insufficient | The allocation cannot fund this action |
| 403 | auth.browser_origin | A secret key was used from a browser |
| 403 | auth.insufficient_scope | The credential does not hold the required scope |
| 422 | pagination.cursor_invalid | The cursor could not be read (e.g. a filter changed mid-pagination) |
| 422 | request.invalid | A field failed validation (extra.errors has the detail) |
| 429 | quota.burst_exceeded | Interactive burst limit hit — wait Retry-After seconds |
| 503 | credits.unavailable | The billing service could not confirm the charge; retry with the same Idempotency-Key |
| 503 | upstream.unavailable | The retrieval engine is unreachable (not charged) |
| 504 | upstream.timeout | The retrieval engine did not answer in time (not charged) |