Talent
Overview
Researcher profiles: education, career, representative work, open source, with Scholar metrics rendered live. One document per person.
- status
- live
- document id
person_ide.g.7870- citation
[talent:7870 Federica Sarro]- updated
- 2026-10-22
Common calls
Look someone up by name
POST /v1/talent/search {"query": "Federica Sarro"}Find people matching criteria
POST /v1/talent/search {"query": "具身智能", "filters": {"org": "清华大学", "role": "教授", "min_h_index": 30}}Read one person
GET /v1/talent/read/7870The fine print
- People with has_profile=false carry only name/affiliation-level data; level=full (and its sections) returns 404.
- Profile content has a daily quota counted in distinct people read per day (talent:profiles; per-plan numbers are in the self-description's quotas): re-reading the same person is free, card / brief and search are not capped. Over the limit returns 429 quota_exceeded with used_today and resets_at. Contact us for a talent:bulk key for volume or offline use (it lifts the scholar_live quota too).
- Common usage is in quickstart: search to look people up or filter them, read (default level=detail) to read one in a single call; other facets via extra=, a human-readable page via format=html; filters marked advanced are there when you need them.
- Facet fields: org / role / area / location / active_since, plus orgs / career_stage (recomputed nightly).
- POST /v1/talent/resolve {names:[…]} checks a batch of names (paper authors, a team page) against the corpus and returns person_ids.
- Name lookup: when the query looks like a person's name (2–4 Chinese characters / 2–4 Latin words), people with that name come first (hit.match="name"); Chinese names are converted to pinyin and Hongjin / Hong Jin / Hong-Jin all match. The response carries name_match: exact (full name matches — a Latin name, or a Chinese name of 3+ characters matched directly) returns only those people; partial (e.g. matched only through pinyin) keeps the normal results after them. mode=name returns only people with that name (ordered by has_profile, then h-index).
- Every [n] in a profile points at an entry in extra=sources; extra=source&n=3 returns the page archived when the profile was researched (text plus the fetch date). Only snapshot=text has readable text — none / blocked (the site refused the crawler) / html (raw page only, add raw=1 for the original HTML) return 404, which is not charged.
- Scholar numbers inside profile.publications are crawl-time values; trust h_index / citations_* in level=brief / detail.
- The closing 'online footprint & contact' section comes from public homepages.
Search
POST
/v1/talent/searchHybrid retrieval, one card per hit. 2 credits. Free sample:
Federica Sarro.Filter fields
| field | type · ops | meaning |
|---|---|---|
| org | keyword · eq any | Current organisation as stored: Chinese institutions under their Chinese name, e.g. 清华大学 (Tsinghua University); several allowed (past or current: advanced field orgs) |
| role | keyword · eq any text教授 · 副教授 · 助理教授 · 研究员 · 博士后 · 博士生 · 硕士生 · 工程师 | Title: the normalised titles match exactly; anything else (or {"text": …}) is a full-text match on the raw title |
| area | keyword · eq any | Research area, e.g. embodied AI, RAG; several allowed |
| location | keyword · eq any | Location as stored: Chinese city names in Chinese, e.g. 北京 (Beijing), 上海 (Shanghai), 香港 (Hong Kong); several allowed. English city names do not match |
| min_h_index | integer · eq | h-index at least |
| active_since | integer · eq | Most recent paper in or after this year (drops inactive people) |
17 more, all usable
| field | type · ops | meaning |
|---|---|---|
| names | text · text | Full-text match on name (zh/en): {"text": "Zhang San"} |
| name_zh | text · text | Chinese name |
| name_en | text · text | English name |
| aff_raw | text · text | Full-text match on the raw affiliation string |
| orgs | keyword · eq any | Normalised organisation (past or current), as stored: Chinese institutions under their Chinese name, e.g. 清华大学 (Tsinghua University) |
| orgs_current | keyword · eq any | Current organisations only |
| role_norm | keyword · eq any教授 · 副教授 · 助理教授 · 研究员 · 博士后 · 博士生 · 硕士生 · 工程师 | Normalised title |
| career_stage | keyword · eq anystudent · junior · senior | student / junior / senior |
| areas | keyword · eq any | Research areas (tags + interests + OpenAlex topics) |
| h_index | integer · eq range | Google Scholar h-index |
| citations_all | integer · eq range | Total citations |
| citations_5y | integer · eq range | Citations in the last five years |
| i10_index | integer · eq range | i10-index |
| last_paper_year | integer · eq range | Year of the most recent paper |
| profile_at | datetime · range | Profile generation time |
| has_profile | bool · eq | Has a full profile (raw readable) |
| has_scholar | bool · eq | Has a Google Scholar page |
Parameters
| Parameter | Type | Description |
|---|---|---|
| query REQUIRED | string | 1–1000 characters. Or an array of up to 5 (batch; hits become results[]). |
| top_k | integer= 10 | 1–100. |
| fields | brief · head= brief | head costs one more credit and returns the head view per hit. |
| filters | json | Filter DSL object (see Getting started); declared fields are listed above. |
| mode | hybrid · dense · bm25 · name= hybrid | Retrieval mode. Leave it out to use the first. |
| offset | integer= 0 | Pagination. |
Example
{ "domain": "talent", "query": "Hongjin Qian", "name_match": "exact",
"hits": [ { "id": "4", "score": 12.6, "match": "name", "brief": { … } } ], "total": null, "warnings": [],
"meta": { "request_id": "req_…", "credits": { "charged": 2, "balance": 1998, "pool": "allowance" }, "latency_ms": 41, "cached": false } } Undeclared filter fields return 400 rather than being ignored silently. Filters combine with AND;
_or / _not are available.A name is looked up, not embedded. When the query looks like a person's name, people with that name come first (
match: "name"); Chinese names go through pinyin and Hongjin / Hong Jin / Hong-Jin all match. name_match says how sure: exact returns only those people, partial keeps the normal results after them, null means nobody by that name.Read
GET
/v1/talent/read/{person_id}Three depths.
detail is the default. Free sample: 7870.Levels
| level | credits | returns |
|---|---|---|
| brief | 1 | Card: name, affiliation, title, areas, h-index, citations, has_profile (what search hits carry as brief) |
| detail (default) | 3 | Everything most callers need in one call (the default, level=detail): card + bio, current organisations, education, career, top 5 papers, Scholar metrics, top 5 coauthors, advisors, and the full profile's section map (read one with level=full§ion=<name>) |
| full | 10 | The full profile markdown (level=full; the contact section is omitted unless contact=1) |
Extras
One side of the same document, in place of a level.
| extra | credits | returns |
|---|---|---|
| scholar | 2 | Structured Google Scholar: metrics (all / 5y), citations by year, top papers, as_of, stale, source. A stale snapshot is rebuilt from cache for free when possible, otherwise queued for background refresh |
| scholar_live | 20 | Same as scholar but synchronously fetches the latest numbers from Google Scholar (≤10s). Subject to a per-account daily quota (talent:scholar_live) and a global crawl budget; if the refresh does not actually happen you get a 502 and the credits and quota back — use extra=scholar for the stored snapshot |
| papers | 2 | Representative papers: Scholar top papers + profile top_papers + OpenAlex works, deduplicated by title, sorted by citations |
| network | 2 | Relations: coauthors (with in-corpus person_id), advisors, students |
| sources | 1 | The profile's reference list: the [n] numbers used in the report, url, title, confidence, whether the page archived at research time is still readable (snapshot), and which facts it backs (backs: education / affiliation) |
| source | 2 | The archived page behind one reference (the snapshot taken at research time; no live fetch). n is the [n] in the report; raw=1 returns the original HTML |
| structured | 3 | Structured profile for section-by-section rendering: education / work with dates (verbatim strings plus parsed start_year / end_year / current), open_source, top_papers, links, bio_md, activities_md, tags, career_stage; every item carries source_ids numbered as in view=sources. No Scholar metrics (live ones are in view=scholar); email only with contact=1; people without a researched profile get 404 (not charged) |
Parameters
| Parameter | Type | Description |
|---|---|---|
| person_id (path) REQUIRED | string | Document id (person_id). |
| level | brief · detail · full= detail | How deep to read. |
| extra | scholar · scholar_live · papers · network · sources · source · structured | Read one side instead of a level. |
| format | json · md · html= json | Response shape. |
| contact | bool= false | (level = full) |
| section | string | (level = full: read one section) |
| characters | integer= 3000 | (level = full: first N characters) |
| n | integer | (extra = source) |
| raw | bool= false | (extra = source) |
Example
{ "domain": "talent", "id": "7870", "level": "detail", "view": "profile", "data": { … } | "text": "…", "token_count": 1834, "meta": { … } } talent:bulk is a permission on the key, not a domain. Lifts talent's daily quotas (profile content and live Scholar refreshes). For callers with a bulk or licence agreement. Everything marked permission is a 403 without it and costs nothing — an empty scope list means every domain, never a permission. Ask for it on the API keys page in the console.A page for people.
format=html returns the profile as a rendered page instead of JSON — open it in a tab or an iframe. It takes the session cookie or ?api_key=.The pages behind a profile. Every
[n] in a profile is a page read when it was researched, and kept. extra=sources lists them with what each one still holds; extra=source&n=6 returns that archived page. Nothing to give you is a 404 and is not charged.The older
GET /v1/talent/doc/{id}?view=… still works.Read many
POST
/v1/talent/readUp to 50 ids, one level. Missing ids come back with
error: "not_found" and are not charged.Parameters
| Parameter | Type | Description |
|---|---|---|
| ids REQUIRED | string[] | Document ids. |
| level | brief · detail · full= detail | Level for every id. |
| extra | scholar · scholar_live · papers · network · sources · source · structured | Read one side instead. |
Example
{ "domain": "talent", "level": "detail", "docs": [ { "id": "…", "data": { … } }, { "id": "…", "error": "not_found" } ], "meta": { … } } Facets
GET
/v1/talent/facets?field={field}Legal values for a filter field, so an agent never guesses; precomputed fields carry counts, declared enums come without. Free, no key.
Parameters
| Parameter | Type | Description |
|---|---|---|
| field REQUIRED | orgs · orgs_current · areas · role_norm · career_stage · location · last_paper_year | Filter field with facets. |
| limit | integer= 50 | Max values. |
Example
{ "domain": "talent", "field": "…", "values": [ { "value": "…", "count": 3120 } ], "meta": { … } } Resolve names
POST
/v1/talent/resolveA batch of names (paper authors, a team page) → in-corpus candidates per name, with
resolved set when exactly one matches. 2 credits per call, up to 50 names.Parameters
| Parameter | Type | Description |
|---|---|---|
| names REQUIRED | string[] | Names as written in the source. |
Example
{ "domain": "talent", "results": [ { "query": "Federica Sarro", "candidates": [ { "person_id": 7870, "name_line": "…", "score": 1 } ], "resolved": 7870 } ], "meta": { … } } Askregistered key+ /stream
POST
/v1/talent/askFind or understand people: an agent searches the corpus and reads profiles, answering with [talent: ] citations; no web access, says so when nobody matches.
effort low / medium / high = 50 / 100 / 200 credits. Append /stream for NDJSON; the first event is always billing. A failure before the first answer_delta is refunded.Parameters
| Parameter | Type | Description |
|---|---|---|
| query REQUIRED | string | 1–2000 characters. Be specific; ask for numbers if you want numbers. |
| top_k | integer= 20 | candidates per corpus search |
| effort | low · medium · high= low | Reading rounds, and the price: 50 / 100 / 200 credits. Your plan caps it. |
| verbose | bool= false | Include the tool-call trace (tool_call / tool_result / thinking events when streaming). |
| top_k | integer= 10 | Speculative prefetch size. |
| stream_answer | bool= true | Streaming only: false emits one answer event instead of deltas. |
| max_rounds | integer | 0–8, overrides the effort preset. |
| force_answer_after | number | Seconds; hard cutover into the answer phase. |
| max_answer_tokens | integer= 4096 | Hitting it sets answer_truncated. |
| language | string | Answer language; defaults to the query’s. |
Example
{ "answer": "… [talent:7870 Federica Sarro] …", "sources": [ … ], "stats": { "rounds": 1, "elapsed_s": 6.2, "answer_truncated": false }, "coverage"?: { … }, "meta": { "credits": { "charged": 50, … } } } Citations are real — every id in
answer exists in this domain (format [talent:7870 Federica Sarro]). sources is the retrieval set, not the citation list. answer_truncated means incomplete.