Valyu API warnings - type, message and detail

A warning means the request succeeded, but part of it was skipped or adjusted. An error (4xx) means nothing could be returned, and nothing was charged. A plan limit never fails a request that can still return something. It succeeds, and the warning says what was left out and what unlocks it.

Warning shape

Responses that can carry warnings have an optional warnings list. It is present only when there is something to say.

{
  "type": "datasets_not_in_plan",
  "message": "Your Pay-as-you-go plan doesn't include valyu/valyu-biorxiv and valyu/valyu-medrxiv (Ridiculously Cheap, $29/mo) and valyu/valyu-chemrxiv (Comfortably Pro, $99/mo), so they were skipped. Results come from your other sources. Comfortably Pro ($99/mo) includes all 3: https://platform.valyu.ai/user/account/billing?tab=plan",
  "detail": {
    "datasets": [
      {"id": "valyu/valyu-biorxiv", "required_plan": "tier_1"},
      {"id": "valyu/valyu-medrxiv", "required_plan": "tier_1"},
      {"id": "valyu/valyu-chemrxiv", "required_plan": "tier_2"}
    ],
    "current_plan": "tier_0",
    "required_plan": {"id": "tier_2", "name": "Comfortably Pro", "price": "$99/mo"},
    "upgrade_url": "https://platform.valyu.ai/user/account/billing?tab=plan"
  }
}

Field	Meaning
`type`	Stable snake_case identifier. New types may be added at any time, so handle ones you don’t recognise.
`message`	A self-contained sentence, safe to show a user or for an agent to relay as-is.
`detail`	Optional, type-specific structured fields, including any URLs.

Plan IDs map to plans as follows: tier_0 Pay-as-you-go, tier_1 Ridiculously Cheap ($29/mo), tier_2 Comfortably Pro ($99/mo), tier_3 Serious Business ($499/mo). See pricing. Datasets that come from a category such as academic are routing candidates, not explicit requests, so skipping them never produces a warning. Only datasets you name explicitly do.

Handling warnings

Read warnings after every successful response. Treat a missing list as empty, and fall back to message for any type you don’t handle.

curl -s https://api.valyu.ai/v1/search \
  -H "x-api-key: $VALYU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "CRISPR off-target effects", "included_sources": ["valyu/valyu-pubmed", "valyu/valyu-biorxiv"]}' \
  | jq -r '.warnings[]?.message'

data = response.json()
for w in data.get("warnings") or []:
    print(w["message"])

const data = await response.json();
for (const w of data.warnings ?? []) {
  console.log(w.message);
}

Branch on type only for the cases you act on in code, for example reading detail.upgrade_url from datasets_not_in_plan to show an upgrade button.

For agents: relay `message` to your user

If you are an agent, pass each warning’s message to your user unedited. It names what was skipped, what that means for the response and the one action that fixes it, with its URL. A warning is not a failure: use the results you got. Datasets on a self-serve plan come with an upgrade_url. Licensed datasets and per-key limits come with a contact_url instead: contact us for access. To pick sources or an upgrade before searching, read required_plan ({id, name, price}, null when licensed separately) for each dataset from GET /v1/datasources.

Search

POST /v1/search returns these types.

`type`	When	`detail`
`datasets_not_in_plan`	Datasets you named that your plan doesn’t include but a self-serve plan does. The rest were searched.	`datasets[{id, required_plan}]`, `current_plan`, `required_plan{id, name, price}`, `upgrade_url`
`datasets_unavailable`	Datasets you named that no self-serve upgrade unlocks: licensed datasets, IDs that aren’t datasets, or datasets your Enterprise plan doesn’t include	`datasets[{id, reason}]` with `reason` `licensed`, `unknown` or `not_in_plan` (outside an Enterprise plan); `contact_url`, `datasources_url`
`datasets_deepresearch_only`	Datasets you named that are only available through DeepResearch. The rest were searched.	`datasets`
`max_num_results_capped`	`max_num_results` was above your key’s limit, so the limit was applied	`requested`, `applied`, `contact_url`
`collection_not_found`	`collection:<name>` matched no collection	`collection`
`collection_unavailable`	A collection couldn’t be resolved, so the search ran without it	`collection`
`source_bias_ignored`	A `source_biases` entry had no effect	`source`, `bias`, `reason` (`not_included` or `excluded`)
`documents_withheld`	Documents from protected datasets were withheld under their access limits	`count`
`source_unavailable`	A source failed while others returned results	`source`

Answer

POST /v1/answer carries the warnings of the searches it ran, deduplicated, in the final metadata event. They use the same types as Search.

DeepResearch

Create task and Get status return warnings in the same shape. A task body always has warnings, [] when there are none. DeepResearch warnings cover only problems with the request itself, never what happens during the run.

`type`	When	`detail`
`datasets_not_in_plan`	Datasets you named that your plan doesn’t include but a self-serve plan does	`datasets[{id, required_plan}]`, `current_plan`, `required_plan{id, name, price}`, `upgrade_url`
`datasets_unavailable`	Datasets you named that no self-serve plan unlocks	`datasets[{id, reason}]`, `contact_url`, `datasources_url`
`tool_not_granted`	A tool that needs a separately licensed grant, for example X search	`tool`, `grant`, `contact_url`
`tool_unavailable`	A tool the chosen mode doesn’t have. The task runs without it, and `message` names the modes that have it.	`tool`, `mode`, `modes_with_tool`
`brand_collection_unsupported`	`brand_collection_id` isn’t supported for this task	None
`collection_not_found`	`collection:<name>` matched no collection	`collection`
`collection_unavailable`	A collection couldn’t be resolved, so the task runs without it	`collection`
`collection_empty`	The collection has no sources	`collection`
`sources_truncated`	`included_sources` expanded past the source limit, so only the first sources are kept	`requested`, `applied`
`deliverable_adjusted`	A deliverable setting, such as `slides`, was clamped or ignored	`field`, `applied`
`skills_unavailable`	Requested skills aren’t available	`skills`
`batch_skills_ignored`	Skills were sent on a batch, which ignores them	None

Older tasks may still hold plain-string warnings. Treat a string as the message. When nothing can be returned, the request fails instead. Plan, credit and limit errors return error (a sentence you can relay), a stable code and a recovery object with the URLs to act on. A 429 puts its sentence in message instead, with error set to rate_limited. Error codes are separate from warning types: dataset_unavailable is an error, datasets_unavailable a warning. See errors for every status.

Status	`code`	When	`recovery`
`402`	`insufficient_credits`	Your balance is used up	`topup_url`, plus `upgrade_url` below the top plan
`402`	`credit_limit_reached`	Your monthly usage limit is reached	`increase_limit_url`
`402`	`spend_cap_reached`	The key’s budget cap is reached	`increase_cap_url`
`403`	`tier_insufficient`	Every dataset you named is outside your plan	`current_plan`, `required_plan{id, name, price}` (or `null`), `required_tier`, `upgrade_url`
`403`	`dataset_unavailable`	Every dataset you named is licensed or unknown	`current_plan`, `contact_url`, `datasources_url`
`403`	`deepresearch_only`	Every dataset you named is only available through DeepResearch	`docs_url`. `restricted_sources` lists the datasets.
`429`	`rate_limited`	You hit your plan’s rate limit for the endpoint	`retry_after`, `plan`, `limit`, `upgrade_url` (`contact_url` on the top plans). They also stay at the top level.

API essentials

Search

Contents

Answer

DeepResearch

DeepResearch (Batch)

Workflows

Datasources

Warnings

Warning shape

Handling warnings

For agents: relay `message` to your user

Search

Answer

DeepResearch

​Warning shape

​Handling warnings

​For agents: relay message to your user

​Search

​Answer

​DeepResearch

​Related errors

Warning shape

Handling warnings

For agents: relay `message` to your user

Search

Answer

DeepResearch

Related errors