Skip to main content

Contents Endpoint Reference

Known-URL extraction surface via POST /contents.
  • Base docs URL: https://exa.ai/docs
  • Contents reference: /reference/get-contents
  • Contents coding-agent reference: /reference/contents-api-guide-for-coding-agents
  • Contents best practices: /reference/contents-best-practices
  • Content freshness: /reference/livecrawling-contents

Contents

  • Overview
  • Request shape
  • Top-level content fields
  • Freshness controls
  • 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

Core Request Parameters

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, and summary are top-level request fields

Content Field Behavior

Pick one of text, highlights, or summary by default. 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 as the normative control for new integrations: 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 new requests and examples.

Response and Statuses

The contents endpoint can return HTTP 200 even when some requested URLs fail. Always inspect statuses.
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

  1. Do not wrap text, highlights, or summary inside a contents object on /contents.
  2. Do not assume HTTP 200 means every URL succeeded; inspect statuses.
  3. Do not add stream: true; the contents endpoint does not support streaming.
  4. Prefer maxAgeHours over older livecrawl strings in new examples.
  5. In Python SDK calls, remember snake_case inside nested options such as max_characters and max_age_hours.
Last modified on June 26, 2026