Ask a question about a person

Required permissions: people:read.

Derived-context capability: people:read includes derived briefing context. For this operation, that scope permits the person record, stored contacts, notes, list membership, synthesis and stakeholder reports, the linked account and its stored research, attached events and rationale, sequences and outcomes, sent emails, composed messages, the LinkedIn profile and posts, and workspace solution and stakeholder criteria. Answers may include facts from this derived context. No additional source scopes are required here, including when the owner role grants only people:read. The key and its owner's current workspace role must both allow people:read. Losing unrelated owner permissions does not block this operation. GET /v1/whoami reports the key's current effective scopes in key.effectiveScopes. Direct account and workspace reads still require accounts:read, and direct event reads events:read. This capability grants no writes or new research. Sources remain limited to the existing person dossier and workspace context; the receipt describes which records informed the answer, subject to existing limits.

Ask anything about one person and get an answer grounded in everything Trayo holds on them. Synchronous and read-only: the answer comes back in one response, typically in 5–15 seconds (the server gives up at 120 seconds by default with 503 person_ask_failed, so set your client timeout above that and retry once on retry_later). The answer is not saved. Public REST and MCP usage is recorded without daily usage caps, workspace quota cutoffs or lookup quotas for now. Workspace request pacing still applies. What goes into the answer. Two kinds of source, rendered into one dossier with sane limits: the person's Trayo record — the contact details on record, the account and its research, the signals (events) the person is attached to and Trayo's reason for each, every sequence composed for them with each step's send/open/reply outcome, emails sent, messages composed, lists, any stored synthesis or stakeholder report, and the note you wrote — plus the LinkedIn profile from Trayo's own data: headline, about, work history with dates, and the person's recent posts.

intent steers the answer. Say what you will do with it — "qualifying whether to sequence them, I need a verdict and the reason", "drafting a first email, I need hooks I can cite", "briefing a rep before a call" — and the focus, depth and form follow. Without it you get a direct, concise answer.

No confidence score is returned — read sources to see what the answer is grounded in. It is a receipt of the records used: how many signals, whether any outreach exists, whether the LinkedIn profile was found. sources.linkedin.status is not_linked when the person has no LinkedIn identity in Trayo (set linkedinUsername with PATCH /v1/people/{id} and ask again), not_found when Trayo has no record for that profile, and unavailable when that data could not be reached this time — the answer then rests on the Trayo record alone. gaps names what was missing.

Grounded, not researched. Trayo answers from these records only: no web search, no guessing. A fact that is not on record is named as unknown. To put more on record first: POST /v1/people/{id}/enrich finds an email or phone, and POST /v1/discoveries puts events and the people attached to them on the account's record.