Skip to main content
POST
/
v1
/
contents
curl --request POST \
  --url https://api.valyu.ai/v1/contents \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "urls": [
    "https://en.wikipedia.org/wiki/Quantum_computing"
  ]
}
'
{
  "success": true,
  "error": null,
  "tx_id": "tx_c1d2e3f4-a5b6-7890-cdef-123456789abc",
  "urls_requested": 2,
  "urls_processed": 2,
  "urls_failed": 0,
  "results": [
    {
      "url": "https://en.wikipedia.org/wiki/Quantum_computing",
      "status": "success",
      "title": "Quantum computing - Wikipedia",
      "content": "# Quantum computing\\n\\nQuantum computing is a type of computation that harnesses quantum mechanical phenomena...",
      "description": "Quantum computing is a type of computation that harnesses quantum mechanical phenomena.",
      "source": "web",
      "price": 0.001,
      "length": 24500,
      "data_type": "unstructured",
      "source_type": "website",
      "image_url": {
        "0": "https://upload.wikimedia.org/quantum.png"
      },
      "screenshot_url": null
    }
  ],
  "total_cost_dollars": 0.002,
  "total_characters": 49000
}

Authorizations

​
X-API-Key
string
header
required

API key for authentication. Get yours at platform.valyu.ai.

Body

application/json

Content extraction request parameters.

​
urls
string<uri>[]
required

URLs to extract content from. Must be valid HTTP/HTTPS URLs. Duplicates are silently removed.

Required array length: 1 - 10 elements
Example:
[
  "https://en.wikipedia.org/wiki/Quantum_computing",
  "https://arxiv.org/abs/2401.00001"
]
​
response_length
default:short

Maximum character length of extracted content per URL.

  • "short" - 25,000 characters (default)
  • "medium" - 50,000 characters
  • "large" - 100,000 characters
  • "max" - No limit
  • Any positive integer for a custom character limit
Available options:
short,
medium,
large,
max
​
max_price_dollars
number

Maximum budget in USD for this request. If estimated cost exceeds this, the request is rejected. Defaults to 2x the maximum possible cost.

Required range: x > 0
Example:

0.05

​
summary
default:false

Controls AI-powered content processing. Adds $0.001 per URL when enabled.

  • false - No AI processing, raw extracted content only (default)
  • true - Generate a text summary of each page
  • "string" - Generate a summary guided by custom instructions (max 500 characters)
  • {json_schema} - Extract structured data matching the provided JSON schema
​
extract_effort
enum<string>
default:auto

Controls how pages are rendered for extraction.

  • "auto" - Automatically selects the best method per URL (default)
  • "normal" - HTTP-only extraction, fastest
  • "high" - Full Chrome rendering, best for JavaScript-heavy pages
Available options:
auto,
normal,
high
​
screenshot
boolean
default:false

Capture a screenshot of each page. Screenshot URL returned in screenshot_url field of each result.

​
async
boolean
default:false

Process URLs asynchronously in the background. Returns a job_id to poll via GET /v1/contents/jobs/{job_id}. Useful for slow, JavaScript-heavy pages.

​
webhook_url
string<uri>

HTTPS URL to receive a webhook POST when async processing completes. Only used when async is true. The webhook payload is signed with HMAC-SHA256.

Example:

"https://your-app.com/webhooks/valyu"

Response

All URLs processed successfully (synchronous).

Synchronous content extraction response.

​
success
boolean
required

Whether the extraction completed successfully.

Example:

true

​
tx_id
string
required

Transaction ID for tracking.

Example:

"tx_a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
urls_requested
integer
required

Number of deduplicated URLs submitted.

Example:

3

​
urls_processed
integer
required

Number of URLs successfully processed.

Example:

3

​
urls_failed
integer
required

Number of URLs that failed processing.

Example:

0

​
results
object[]
required

Extraction results for each URL.

​
total_cost_dollars
number
required

Total cost in USD (only successful URLs are charged).

Example:

0.003

​
total_characters
integer
required

Sum of all result content lengths.

Example:

45230

​
error
string | null

Error message if some URLs failed. null on complete success.

Example:

null