Contents Endpoint Reference
Known-URL extraction surface via POST /contents.
Canonical Docs Links
- Base docs URL:
https://exa.ai/docs - Contents reference:
/reference/get-contents - Contents coding-agent reference:
/contents/quickstart - Contents best practices:
/contents/quickstart - Content freshness:
/contents/quickstart#content-freshness - Exa Snapshot:
/search/snapshot
Contents
- Overview
- Request shape
- Top-level content fields
- Freshness controls
- Snapshot
- Response and statuses
- Critical pitfalls
Overview
Use the contents endpoint when:
- you already know the URLs
- you need clean extraction without first running a search query
- freshness and crawl behavior matter enough to control directly
- you want the search endpoint and contents endpoint separated into two explicit calls
Request Shape
POST https://api.exa.ai/contents
{
"urls": ["https://arxiv.org/abs/2307.06435"],
"highlights": true
}Core Request Parameters
| Parameter | Type | Notes |
|---|---|---|
urls |
string[] | Primary way to pass known URLs |
ids |
string[] | Backwards-compatible alias for document IDs from prior Exa calls |
text |
boolean or object | Top-level text extraction control |
highlights |
boolean or object | Top-level highlights extraction control |
summary |
boolean or object | Top-level summary extraction control |
maxAgeHours |
integer | Normative freshness control |
snapshotAsOf |
string (ISO 8601 date-time) | Exa Snapshot: serve the newest stored version of each page at or before this instant |
livecrawlTimeout |
integer | Timeout in milliseconds |
subpages |
integer | Crawl linked subpages |
subpageTarget |
string or string[] | Focus which subpages to crawl |
extras |
object | Extra link and image extraction |
Top-Level Content Fields
This is the most important shape difference in the Exa platform:
- on the search endpoint, content fields are nested inside
contents - on the contents endpoint,
text,highlights, andsummaryare top-level request fields
from exa_py import Exa
exa = Exa(api_key="YOUR_EXA_API_KEY")
result = exa.get_contents(
["https://exa.ai/docs"],
highlights=True
)Content Field Behavior
| Field | Best For | Notes |
|---|---|---|
text |
Full extraction | Supports maxCharacters, includeHtmlTags, verbosity, includeSections, excludeSections; object options require an explicit task requirement |
highlights |
Token-efficient excerpts | Good default for all tasks unless otherwise specified; use bare true |
summary |
Per-page compression | Each page adds its own synthesis step; only when the user explicitly requests Exa-side summaries |
Pick exactly one of text, highlights, or summary. Stacking them is unnecessary. summary adds a per-page LLM call, and combining text with highlights increases billing for two views of the same page.
Freshness Controls
Use maxAgeHours for crawl freshness. It caps how old cached page content may be before Exa livecrawls; it does not filter by publication date:
| Value | Behavior |
|---|---|
| omitted | Default behavior; cached content first, crawl fallback when needed |
| positive integer | Accept cache up to that age, then live crawl |
0 |
Always live crawl |
-1 |
Cache only |
Set livecrawlTimeout whenever live crawling matters so slow pages do not block the whole request longer than expected.
Do not send livecrawl and maxAgeHours together; prefer maxAgeHours in requests.
Snapshot
Top-level snapshotAsOf (ISO 8601 date-time) serves the newest stored version of each page at or before that instant instead of the current page: Exa Snapshot. It is the opposite of maxAgeHours; never send both. Full request shapes, statuses, and limits are in references/snapshot.md.
Response and Statuses
The contents endpoint can return HTTP 200 even when some requested URLs fail. Always inspect statuses.
{
"results": [
{
"url": "https://example.com",
"text": "..."
}
],
"statuses": [
{ "id": "https://example.com", "status": "success" },
{ "id": "https://failed-url.example.com", "status": "error" }
]
}Common status/error tags include crawl timeout, unsupported URL, source unavailable, and not found conditions. Treat statuses as part of normal control flow, not as a rare exception path.
Critical Pitfalls
- Do not wrap
text,highlights, orsummaryinside acontentsobject on/contents. - Do not assume HTTP 200 means every URL succeeded; inspect
statuses. - Do not add
stream: true; the contents endpoint does not support streaming. - Prefer
maxAgeHoursover olderlivecrawlstrings in new examples. - In Python SDK calls, remember
snake_caseinside nested options such asmax_charactersandmax_age_hours.