The service currently runs on a single small machine: about 50 search requests/s and ~20 concurrent ask sessions across all users. Please keep concurrency modest (≤ 5 per client) and back off on 429 using Retry-After. Details →

Talent

Overview

Researcher profiles: education, career, representative work, open source, with Scholar metrics rendered live. One document per person.

status
live
document id
person_id e.g. 7870
citation
[talent:7870 Federica Sarro]
updated
2026-10-22

Common calls

Look someone up by namePOST /v1/talent/search {"query": "Federica Sarro"}
Find people matching criteriaPOST /v1/talent/search {"query": "具身智能", "filters": {"org": "清华大学", "role": "教授", "min_h_index": 30}}
Read one personGET /v1/talent/read/7870
The 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.

Read

GET/v1/talent/read/{person_id}
Three depths. detail is the default. Free sample: 7870.

Levels

levelcreditsreturns
brief1Card: name, affiliation, title, areas, h-index, citations, has_profile (what search hits carry as brief)
detail (default)3Everything 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&section=<name>)
full10The 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.

extracreditsreturns
scholar2Structured 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_live20Same 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
papers2Representative papers: Scholar top papers + profile top_papers + OpenAlex works, deduplicated by title, sorted by citations
network2Relations: coauthors (with in-corpus person_id), advisors, students
sources1The 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)
source2The 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
structured3Structured 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

ParameterTypeDescription
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/read
Up to 50 ids, one level. Missing ids come back with error: "not_found" and are not charged.

Parameters

ParameterTypeDescription
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

ParameterTypeDescription
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/resolve
A 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

ParameterTypeDescription
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/ask
Find 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

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