Ask a relationship question

false when the sides cannot be meaningfully weighed — one found nobody, or the counts are approximate. The sides are still returned; what is withheld is the comparison.

Applied to both sides. A comparison across two readings of *knows* is not a comparison.

One per half of your question, in the order you asked.

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

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

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

Present only when the question asked for a breakdown.

false when a count is an estimate, when values were merged under one label, or when the question required several institutions at once — each group is then an upper bound.

The value as the index holds it.

employment or education, for an institution breakdown.

What to show: a department or seniority label, or the institution's name.

Distinct people in this group. ≥ 0.

Smaller groups exist and were not returned.

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

Which definition of *knows* produced number_of_contacts_overlapping_tenure_with. overlapping — the two people were at the shared institution at the same time. shared — both were there at some point, which on a large employer counts everyone who ever passed through. Echoed because it changes what the number means, not by a little: one measured row counts 16,630 people under overlapping and 100,085 under shared.

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

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

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

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

How many of them this answer carries. ≥ 0.

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

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

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

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

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

Which limit stopped the enumeration short, when one did.

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

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

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

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

Distinct people at the first company.

Distinct people at the second company.

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

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

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

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

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

*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.

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.

Always person. Present so a row is self-describing in the same way every other category's rows are.

Present only with include_company_context.

Currently employed or enrolled at the other company/side specifically — not merely at some institution shared with it. Renamed from currently_there, which was scored over *any* matched institution: a person still enrolled at a shared university could read currently_there: true with no employment at the other side at all. This field answers the narrower, correct question, in parity with is_alum, which was always scoped this way.

The same department vocabulary the request filters on.

Use with POST /v1/entities/persons for the full record.

Previously worked at the company on the other side. The strongest single signal, and weighted accordingly.

How many distinct institutions connect this person to the other side. Exact, not an estimate — 0 never appears here, because a row with no reason is not returned at all (see via). The sort key when ranking by strength of connection rather than by name.

Every reason this person matched, as a phrase — array[0] is the strongest. Not via's own order: via is ordered by how many affiliation records back an institution, which is a volume measure, not a strength one. This array is ranked by connection strength instead — currently employed at the other side outranks having once shared a school with someone there. Each entry corresponds 1:1 to a via entry's own match_type, just reordered. Read together, not as two independent sources of truth.

How many people at the other company this person can reach. 0 is a computed, checked answer — we ran the count and found nobody reachable under the current connection_basis. It is not the same as null/absent, which means the count was never attempted: a via_institution query has no other side to count against, so it is skipped rather than defaulted to 0. Read it together with connection_basis on the envelope — the same person counts 16,630 under overlapping and 100,085 under shared, because sharing a large former employer means sharing it with everyone who ever worked there.

False when the affiliation graph knows this person but the entity index has no record for them — a real connection with a thin profile. They are returned rather than dropped: removing them would shrink a page while leaving total describing the unshrunk set.

Why this person matched. Never empty on a returned row.

When it ended. Absent means still there.

The institution's key in the affiliation corpus. Stable, and the value to send back when narrowing to this institution.

employment — a shared employer — or education.

How this institution was identified: url from a canonical LinkedIn URL, edu from a school record, or name from a normalised name. Always returned, because name matches are a genuinely weaker signal — names are not unique — and a connection shown without this reads as verified when it is an inference.

Why this specific institution counts as a reason — in words, not a code. "Currently works at Acme", "Previously worked at Acme", "Also worked at McKinsey" (a third company both sides happen to share), or "Attended Stanford University". Spelled out rather than an enum because this API is callable by an LLM directly — a code needing a lookup table defeats that. The row's own top-level match_type is this same string, one per via entry, reordered so the strongest reason leads.

What they did there — a job title, or a degree for a school. Returned because a shared employer with no overlap in time is a much weaker claim than one with it, and a caller shown only the institution's name cannot tell the two apart.

When this person's association began, YYYY-MM-DD.

Present only when the question asked for a proportion.

Every person currently at the subject company who meets the same person filters, with no connection required. The denominator. ≥ 0.

total / population. null when the population is zero. ≥ 0, ≤ 1.

The half of your question this side answers, in your own words.

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

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

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

One ready-to-show sentence.

≥ 0.

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

Index into sides, or null when no side is named. null is a real answer, not a missing one, and it covers more than a tie: if either count is approximate the two cannot be ranked against each other, because the difference between them may be smaller than the error on either. Both counts are still reported — read them rather than this field when it is null.

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

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

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

Present only when the question asked for a breakdown.

false when a count is an estimate, when values were merged under one label, or when the question required several institutions at once — each group is then an upper bound.

The value as the index holds it.

employment or education, for an institution breakdown.

What to show: a department or seniority label, or the institution's name.

Distinct people in this group. ≥ 0.

Smaller groups exist and were not returned.

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

Which definition of *knows* produced number_of_contacts_overlapping_tenure_with. overlapping — the two people were at the shared institution at the same time. shared — both were there at some point, which on a large employer counts everyone who ever passed through. Echoed because it changes what the number means, not by a little: one measured row counts 16,630 people under overlapping and 100,085 under shared.

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

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

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

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

How many of them this answer carries. ≥ 0.

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

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

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

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

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

Which limit stopped the enumeration short, when one did.

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

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

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

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

One per person that could be drilled into, in the same rank order as results. Shorter than k when a row carries no LinkedIn URL — see skipped, which is why a short list is never a claim that somebody can reach nobody.

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

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

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

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

overlapping — the two people were at the shared institution at the same time. shared — both were there at some point. Echoed because it decides which rows exist at all here, not just how a count is worded.

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

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

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

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

How many of them this answer carries. ≥ 0.

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

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

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

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

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

Which limit stopped the enumeration short, when one did.

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

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

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

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

Every institution connecting the anchor to people at the target company, with how many people each one reaches. Describes the whole answer, not this page — the rows are a window, this is not.

The institution's key in the affiliation corpus. The same value POST /v1/relationships returns, and the value to send back as an institutions[] anchor there to narrow to this one.

employment — a shared employer — or education.

How this institution was identified: url from a canonical LinkedIn URL, edu from a school record, or name from a normalised name. name matches are a genuinely weaker signal, because names are not unique.

Distinct people at the target company reachable through this institution. Always a real count, never null: an institution nobody is behind is not returned at all. Read it together with the envelope's connection_basis — under shared a large former employer counts everyone who ever passed through it, so the same institution can count an order of magnitude higher than under overlapping.

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

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

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

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

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

The id in results of the person this hangs under.

*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.

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.

*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.

Why this person is reachable. Never empty on a returned row — sharing something with the anchor is the only reason they are here.

What the person you asked through did there.

employment — a shared employer — or education.

Why this counts as a connection, in words. Overlap-aware when the dates allow it — "Overlapped at Acme for 14 months" — and a plainer "Also worked at Acme" / "Attended Stanford University together" when either side's dates are unknown. The row's own top-level match_type is this same string, one per how entry, reordered by strength.

Whole months the two were there at the same time. Absent when either side's start date is unknown — not 0, which would say they were never there together. That is a stronger claim than not knowing, and the difference matters: an overlap of three years and an overlap of one month are otherwise the same row.

Absent means still there.

What the reachable person did there.

Use with POST /v1/entities/persons for the full record.

Every reason this person is reachable, as a phrase — array[0] is the strongest connection. A longer, known overlap outranks an unknown-duration one. Each entry corresponds 1:1 to a how entry's own match_type, reordered by strength rather than by how's own order, which reflects fetch order, not connection quality.

When the question ran through several named people: which of them (by person id) can reach this person.

When the question reached into several companies: which one this person is at, as an index into the envelope's targets. ≥ 0.

When the question ran through several named people: how many each one reaches on their own. total is then the sum of these — an upper bound, since somebody reachable by two of them counts twice.

The named person's id.

≥ 0.

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

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

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

One ready-to-show sentence.

When the question reached into several companies: each one, what it resolved to and how many it holds. Rows are grouped by company in this order, each row's target_index says which, and limit applies per company. total is then the sum of these — exact, since one person has one current employer.

The company it resolved to.

Rows at this company carry the same target_index. ≥ 0.

What it resolved to, by name. Read this before trusting a zero.

Set when this name resolved to the same company as an earlier target. That company was reached once; its rows and total are under the index this points to, and this entry holds none of its own. ≥ 0.

People reachable at this company. ≥ 0.

The company as the question named it.

≥ 0.

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

Distinct people at the first company.

Distinct people at the second company.

How many of the results were drilled into. Capped: each drill-down is a full search, so this is the one question whose cost multiplies. ≥ 1.

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

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

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

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

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

*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.

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.

Always person. Present so a row is self-describing in the same way every other category's rows are.

Present only with include_company_context.

Currently employed or enrolled at the other company/side specifically — not merely at some institution shared with it. Renamed from currently_there, which was scored over *any* matched institution: a person still enrolled at a shared university could read currently_there: true with no employment at the other side at all. This field answers the narrower, correct question, in parity with is_alum, which was always scoped this way.

The same department vocabulary the request filters on.

Use with POST /v1/entities/persons for the full record.

Previously worked at the company on the other side. The strongest single signal, and weighted accordingly.

How many distinct institutions connect this person to the other side. Exact, not an estimate — 0 never appears here, because a row with no reason is not returned at all (see via). The sort key when ranking by strength of connection rather than by name.

Every reason this person matched, as a phrase — array[0] is the strongest. Not via's own order: via is ordered by how many affiliation records back an institution, which is a volume measure, not a strength one. This array is ranked by connection strength instead — currently employed at the other side outranks having once shared a school with someone there. Each entry corresponds 1:1 to a via entry's own match_type, just reordered. Read together, not as two independent sources of truth.

How many people at the other company this person can reach. 0 is a computed, checked answer — we ran the count and found nobody reachable under the current connection_basis. It is not the same as null/absent, which means the count was never attempted: a via_institution query has no other side to count against, so it is skipped rather than defaulted to 0. Read it together with connection_basis on the envelope — the same person counts 16,630 under overlapping and 100,085 under shared, because sharing a large former employer means sharing it with everyone who ever worked there.

False when the affiliation graph knows this person but the entity index has no record for them — a real connection with a thin profile. They are returned rather than dropped: removing them would shrink a page while leaving total describing the unshrunk set.

Why this person matched. Never empty on a returned row.

When it ended. Absent means still there.

The institution's key in the affiliation corpus. Stable, and the value to send back when narrowing to this institution.

employment — a shared employer — or education.

How this institution was identified: url from a canonical LinkedIn URL, edu from a school record, or name from a normalised name. Always returned, because name matches are a genuinely weaker signal — names are not unique — and a connection shown without this reads as verified when it is an inference.

Why this specific institution counts as a reason — in words, not a code. "Currently works at Acme", "Previously worked at Acme", "Also worked at McKinsey" (a third company both sides happen to share), or "Attended Stanford University". Spelled out rather than an enum because this API is callable by an LLM directly — a code needing a lookup table defeats that. The row's own top-level match_type is this same string, one per via entry, reordered so the strongest reason leads.

What they did there — a job title, or a degree for a school. Returned because a shared employer with no overlap in time is a much weaker claim than one with it, and a caller shown only the institution's name cannot tell the two apart.

When this person's association began, YYYY-MM-DD.

Present only when the question asked for a proportion.

Every person currently at the subject company who meets the same person filters, with no connection required. The denominator. ≥ 0.

total / population. null when the population is zero. ≥ 0, ≤ 1.

People in the top k that could not be drilled into. Reaching through somebody needs their LinkedIn URL, and a row without one is skipped rather than guessed at. ≥ 0.

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

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

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

One ready-to-show sentence.

≥ 0.

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

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

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

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

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

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

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

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

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

How many of them this answer carries. ≥ 0.

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

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

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

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

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

Which limit stopped the enumeration short, when one did.

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

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

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

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

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

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

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

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

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

*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.

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.

Distinct people at the first company.

Distinct people at the second company.

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

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

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

One ready-to-show sentence.

≥ 0.

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

true when more institutions qualified than limit returned. A first-class field rather than a degradation[] entry, because it is the one thing about this response a caller must branch on and has_more — the field they would normally read for it — is structurally false here. A clipped list that looked complete would be a wrong answer rather than a short one: institutions is frequently the whole point ("you both know people from Stanford and McKinsey"). Raise limit, or narrow with institution_type / name_starts_with, to see the rest. degradation[] still carries anything the upstream itself reported about the answer being narrower than the question; this field is not restated there, because one condition reported twice is a condition clients learn to ignore.

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

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

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

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

overlapping — the two people were at the shared institution at the same time. shared — both were there at some point. Echoed because it decides which rows exist at all here, not just how a count is worded.

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

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

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

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

How many of them this answer carries. ≥ 0.

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

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

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

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

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

Which limit stopped the enumeration short, when one did.

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

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

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

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

Every institution connecting the anchor to people at the target company, with how many people each one reaches. Describes the whole answer, not this page — the rows are a window, this is not.

The institution's key in the affiliation corpus. The same value POST /v1/relationships returns, and the value to send back as an institutions[] anchor there to narrow to this one.

employment — a shared employer — or education.

How this institution was identified: url from a canonical LinkedIn URL, edu from a school record, or name from a normalised name. name matches are a genuinely weaker signal, because names are not unique.

Distinct people at the target company reachable through this institution. Always a real count, never null: an institution nobody is behind is not returned at all. Read it together with the envelope's connection_basis — under shared a large former employer counts everyone who ever passed through it, so the same institution can count an order of magnitude higher than under overlapping.

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

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

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

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

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

*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.

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.

*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.

Why this person is reachable. Never empty on a returned row — sharing something with the anchor is the only reason they are here.

What the person you asked through did there.

employment — a shared employer — or education.

Why this counts as a connection, in words. Overlap-aware when the dates allow it — "Overlapped at Acme for 14 months" — and a plainer "Also worked at Acme" / "Attended Stanford University together" when either side's dates are unknown. The row's own top-level match_type is this same string, one per how entry, reordered by strength.

Whole months the two were there at the same time. Absent when either side's start date is unknown — not 0, which would say they were never there together. That is a stronger claim than not knowing, and the difference matters: an overlap of three years and an overlap of one month are otherwise the same row.

Absent means still there.

What the reachable person did there.

Use with POST /v1/entities/persons for the full record.

Every reason this person is reachable, as a phrase — array[0] is the strongest connection. A longer, known overlap outranks an unknown-duration one. Each entry corresponds 1:1 to a how entry's own match_type, reordered by strength rather than by how's own order, which reflects fetch order, not connection quality.

When the question ran through several named people: which of them (by person id) can reach this person.

When the question reached into several companies: which one this person is at, as an index into the envelope's targets. ≥ 0.

When the question ran through several named people: how many each one reaches on their own. total is then the sum of these — an upper bound, since somebody reachable by two of them counts twice.

The named person's id.

≥ 0.

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

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

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

One ready-to-show sentence.

When the question reached into several companies: each one, what it resolved to and how many it holds. Rows are grouped by company in this order, each row's target_index says which, and limit applies per company. total is then the sum of these — exact, since one person has one current employer.

The company it resolved to.

Rows at this company carry the same target_index. ≥ 0.

What it resolved to, by name. Read this before trusting a zero.

Set when this name resolved to the same company as an earlier target. That company was reached once; its rows and total are under the index this points to, and this entry holds none of its own. ≥ 0.

People reachable at this company. ≥ 0.

The company as the question named it.

≥ 0.

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

How many searches this answer took. ≥ 1.

The part of your question this answer covers, in your own words. On a single question it is the whole sentence.

What was widened, capped or could not be applied — in plain language, one entry per thing. Empty means nothing was dropped.

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

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

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

Present only when the question asked for a breakdown.

false when a count is an estimate, when values were merged under one label, or when the question required several institutions at once — each group is then an upper bound.

The value as the index holds it.

employment or education, for an institution breakdown.

What to show: a department or seniority label, or the institution's name.

Distinct people in this group. ≥ 0.

Smaller groups exist and were not returned.

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

Which definition of *knows* produced number_of_contacts_overlapping_tenure_with. overlapping — the two people were at the shared institution at the same time. shared — both were there at some point, which on a large employer counts everyone who ever passed through. Echoed because it changes what the number means, not by a little: one measured row counts 16,630 people under overlapping and 100,085 under shared.

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

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

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

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

How many of them this answer carries. ≥ 0.

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

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

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

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

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

Which limit stopped the enumeration short, when one did.

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

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

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

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

Distinct people at the first company.

Distinct people at the second company.

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

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

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

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

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

*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.

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.

Always person. Present so a row is self-describing in the same way every other category's rows are.

Present only with include_company_context.

Currently employed or enrolled at the other company/side specifically — not merely at some institution shared with it. Renamed from currently_there, which was scored over *any* matched institution: a person still enrolled at a shared university could read currently_there: true with no employment at the other side at all. This field answers the narrower, correct question, in parity with is_alum, which was always scoped this way.

The same department vocabulary the request filters on.

Use with POST /v1/entities/persons for the full record.

Previously worked at the company on the other side. The strongest single signal, and weighted accordingly.

How many distinct institutions connect this person to the other side. Exact, not an estimate — 0 never appears here, because a row with no reason is not returned at all (see via). The sort key when ranking by strength of connection rather than by name.

Every reason this person matched, as a phrase — array[0] is the strongest. Not via's own order: via is ordered by how many affiliation records back an institution, which is a volume measure, not a strength one. This array is ranked by connection strength instead — currently employed at the other side outranks having once shared a school with someone there. Each entry corresponds 1:1 to a via entry's own match_type, just reordered. Read together, not as two independent sources of truth.

How many people at the other company this person can reach. 0 is a computed, checked answer — we ran the count and found nobody reachable under the current connection_basis. It is not the same as null/absent, which means the count was never attempted: a via_institution query has no other side to count against, so it is skipped rather than defaulted to 0. Read it together with connection_basis on the envelope — the same person counts 16,630 under overlapping and 100,085 under shared, because sharing a large former employer means sharing it with everyone who ever worked there.

False when the affiliation graph knows this person but the entity index has no record for them — a real connection with a thin profile. They are returned rather than dropped: removing them would shrink a page while leaving total describing the unshrunk set.

Why this person matched. Never empty on a returned row.

When it ended. Absent means still there.

The institution's key in the affiliation corpus. Stable, and the value to send back when narrowing to this institution.

employment — a shared employer — or education.

How this institution was identified: url from a canonical LinkedIn URL, edu from a school record, or name from a normalised name. Always returned, because name matches are a genuinely weaker signal — names are not unique — and a connection shown without this reads as verified when it is an inference.

Why this specific institution counts as a reason — in words, not a code. "Currently works at Acme", "Previously worked at Acme", "Also worked at McKinsey" (a third company both sides happen to share), or "Attended Stanford University". Spelled out rather than an enum because this API is callable by an LLM directly — a code needing a lookup table defeats that. The row's own top-level match_type is this same string, one per via entry, reordered so the strongest reason leads.

What they did there — a job title, or a degree for a school. Returned because a shared employer with no overlap in time is a much weaker claim than one with it, and a caller shown only the institution's name cannot tell the two apart.

When this person's association began, YYYY-MM-DD.

Present only when the question asked for a proportion.

Every person currently at the subject company who meets the same person filters, with no connection required. The denominator. ≥ 0.

total / population. null when the population is zero. ≥ 0, ≤ 1.

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

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

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

One ready-to-show sentence.

≥ 0.

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