Skip to main content
Use Valyu to retrieve information for your own application or run a research task. This page covers what every request has in common. The endpoint pages give full parameters and response schemas.

Choose an endpoint

If this is your first request, follow the quickstart. To control how old a cached page can be, set max_age on Contents.

Base URL and authentication

Every request goes to https://api.valyu.ai and carries your API key in the x-api-key header. Request and response bodies are JSON.
cURL
Create a key in the platform and load it from your application’s environment. The header is x-api-key, not Authorization: Bearer. Keep the key on the server; do not expose it in browser code.

Errors

Error bodies always include error. Search, Contents and Datasources errors usually add "success": false. Requests rejected before they reach an endpoint (a missing or disabled key, or a rate limit) return error and message, and DeepResearch errors return error only. Some errors add a machine-readable code; branch on the status and code rather than the message text. Search and Contents return 206 when the request succeeded only in part, for example when some sources or URLs failed. Treat it as a success and inspect the individual results.

Warnings

A request that succeeds with something skipped or adjusted, such as a named dataset outside your plan, returns a warnings list of {type, message, detail} objects. A plan limit never fails a request that can still return something. See warnings for every type.

Rate limits

Limits apply per organisation and per endpoint. Search, Contents, and creating or polling DeepResearch tasks each have their own limit. The limit is lower on cheaper plans and higher on paid plans. See pricing and plans for the rate on each plan. There is no daily quota. A request over the limit returns 429 Too Many Requests with a Retry-After header, in seconds. The body names the limit you hit and how to raise it:
Wait retry_after seconds, then retry with backoff. A 429 is temporary and clears on its own: it is not a billing or credit problem, and a rate-limited request is never charged.

Pricing

You pay per use from your credit balance. Search is priced per result returned, Contents per extracted URL, and DeepResearch per task by mode. Cost fields in a response (price, total_deduction_dollars, total_cost_dollars, cost) report what each request was charged. See pricing for rates and plans.

Versioning

All endpoints are under /v1. New optional parameters and response fields are added within v1, so ignore fields your client doesn’t recognise. Changes are announced in the API changelog.

OpenAPI specification

Use the OpenAPI 3.0 specification to inspect request and response shapes, generate a client or import requests into an API tool. Open the OpenAPI specification to view or save the raw JSON.
1

Import the specification

In Postman, choose Import and enter https://docs.valyu.ai/api-reference/openapi.json.
2

Configure authentication

Set the API key used by the imported collection’s x-api-key header. Keep the value in a private environment variable.
3

Send a small request

Start with Search and inspect the returned results. Use the async lifecycle documented for research tasks and extraction jobs.

Machine-readable documentation

Documentation index

Find the guide or reference page for a particular integration task.

Documentation MCP

Search the documentation from an MCP client.

Page Markdown

Append .md to a documentation URL to retrieve its text.