Response Detail
Most Ultralayer search endpoints accept a detail parameter that controls how much of each result is returned. It exists primarily for agents and AI workflows, where every unused field burns context window. The same object shape is always used — lower levels simply omit keys.
Billing is unchanged: you pay for the records you retrieve, not for how verbose the JSON is.
Who should use it
Agents & AI tools
Context is the scarce resource. Prefer a reduced detail so the model sees what it needs to reason and cite — not every optional score, quote, and metadata field. Start with standard for normal work.
Direct API consumers
Prefer detail: "full" (the default) and select the fields you care about in your own code. You already control your client; there is little reason to shrink the payload on the server unless you are also stuffing responses into an LLM context.
The levels
Default is always full. Omitting detail keeps backward-compatible, complete responses.
Only what is needed to understand the result for analysis, plus cheap identifiers that unlock follow-up calls (for example a development id, event id, or wire id). Ranking scores, similarity metrics, and bulky provenance are usually omitted unless the score is the finding (for example a signed impact score).
Essential plus enough provenance to cite — typically identity, URL, and a title when one exists. Still selective: not “everything except the largest field.” This is the recommended default for agent calls.
The complete response: scores, quotes, classifications, and full nested objects as documented for each endpoint.
Not every endpoint implements every level. Some expose full / standard / essential; a few expose only full / essential when a middle tier adds little. View the API reference to see which level of detail is supported.
Shape contract
Lower detail never redesigns the object. Keys that remain use the same names and nesting as in full. Nested objects may simply carry fewer keys. Clients and UIs can assume the full shape and treat missing fields as absent — they do not need a separate schema per level.
Code
Rough size reduction
Savings vary by endpoint and by how large a “full” package is (developments and stakeholder identification are heavier than a wire headline). In practice, relative to full:
standardoften cuts on the order of about a third of response tokens.essentialoften cuts roughly half to most of the payload — sometimes substantially more on the largest analytical responses.
Treat these as order-of-magnitude guides for choosing a level, not as guarantees for every call. Prefer standard unless you are packing many results into a tight context (essential) or you truly need quotes, full scores, and complete metadata (full).
Practical guidance
- Agents: pass
"detail": "standard"on search and retrieve calls unless you have a reason not to. Escalate tofullwhen you need source quotes or fields that standard drops; drop toessentialfor dense scans. - API integrations & notebooks: leave the default (
full) and project fields client-side. - Alerts: if the underlying endpoint supports
detail, pin it in the alert’s stored arguments so every poll returns the verbosity you intend. - Follow-ups: identifiers kept at reduced detail (wire id, development id, event id) are enough to fetch a richer package later when you need it.
For field-level behavior on each tool, see the skill pages under Capabilities.