# Valyu API — Orthogonal API

> Pay-per-use API on Orthogonal. Each call is billed to your Orthogonal balance.
> Base API: `https://api.orth.sh/v1/run` · [llms.txt](https://orthogonal.com/llms.txt) · [browse all APIs](https://orthogonal.com/discover)

Valyu’s Search API lets your AI search for the information it needs. Access high-quality content from the web and proprietary sources, with full-text multimodal retrieval.

**Verified:** no

## Access

**Run API:** `POST https://api.orth.sh/v1/run`
**Auth:** `Authorization: Bearer $ORTHOGONAL_API_KEY`
Get an API key at https://orthogonal.com/dashboard/settings/api-keys

Every call goes through the unified Run API: send the API `slug`, the endpoint `path`, and the `query`/`body` parameters. The response is `{ "success": true, "price": "<usd>", "data": { ... } }`.

## Endpoints

### Get Status

Reference for getting deep research task status via GET /v1/deepresearch/tasks/{id}/status.

`GET /v1/deepresearch/tasks/{id}/status`

**Estimated cost:** $0.01

**Docs:** https://docs.valyu.ai/api-reference/endpoint/deepresearch-status

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {id} in "path" with real values before sending
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"valyu","path":"/v1/deepresearch/tasks/{id}/status","method":"GET"}'
```

### Update Task

Reference for adding follow-up instructions to a running task via POST /v1/deepresearch/tasks/{id}/update.

`POST /v1/deepresearch/tasks/{id}/update`

**Estimated cost:** $0.01

**Docs:** https://docs.valyu.ai/api-reference/endpoint/deepresearch-update

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `instruction` | string | Yes | Follow-up instruction to add to the running task. Must be submitted before the writing phase begins. |

```bash
# Replace {id} in "path" with real values before sending
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"valyu","path":"/v1/deepresearch/tasks/{id}/update","body":{"instruction":"<string>"}}'
```

### Cancel Task

Reference for cancelling a running task via POST /v1/deepresearch/tasks/{id}/cancel.

`POST /v1/deepresearch/tasks/{id}/cancel`

**Estimated cost:** $0.01

**Docs:** https://docs.valyu.ai/api-reference/endpoint/deepresearch-cancel

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {id} in "path" with real values before sending
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"valyu","path":"/v1/deepresearch/tasks/{id}/cancel"}'
```

### Delete Task

Reference for deleting a task via DELETE /v1/deepresearch/tasks/{id}/delete.

`DELETE /v1/deepresearch/tasks/{id}/delete`

**Estimated cost:** $0.01

**Docs:** https://docs.valyu.ai/api-reference/endpoint/deepresearch-delete

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {id} in "path" with real values before sending
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"valyu","path":"/v1/deepresearch/tasks/{id}/delete","method":"DELETE"}'
```

### Get Batch Status

Reference for getting batch status via GET /v1/deepresearch/batches/.

`GET /v1/deepresearch/batches/{id}`

**Estimated cost:** $0.01

**Docs:** https://docs.valyu.ai/api-reference/endpoint/deepresearch-batch-status

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {id} in "path" with real values before sending
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"valyu","path":"/v1/deepresearch/batches/{id}","method":"GET"}'
```

### List Batch Tasks

Reference for listing tasks in a batch via GET /v1/deepresearch/batches//tasks.

`GET /v1/deepresearch/batches/{id}/tasks`

**Estimated cost:** $0.01

**Docs:** https://docs.valyu.ai/api-reference/endpoint/deepresearch-batch-list-tasks

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {id} in "path" with real values before sending
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"valyu","path":"/v1/deepresearch/batches/{id}/tasks","method":"GET"}'
```

### Cancel Batch

Reference for cancelling a batch via POST /v1/deepresearch/batches//cancel.

`POST /v1/deepresearch/batches/{id}/cancel`

**Estimated cost:** $0.01

**Docs:** http://docs.valyu.ai/api-reference/endpoint/deepresearch-batch-cancel

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {id} in "path" with real values before sending
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"valyu","path":"/v1/deepresearch/batches/{id}/cancel"}'
```

### Search

Reference for the Valyu Search endpoint to search the web, research, and proprietary datasets via POST /v1/search.

`POST /v1/search`

**Estimated cost:** $0.01

**Docs:** https://docs.valyu.ai/api-reference/endpoint/search

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | The query string for the search |
| `max_num_results` | integer | No | Maximum number of results to return (1-20 for standard API keys, up to 100 with a special API key) |
| `search_type` | enum<string> | No | Type of search to perform.'web' searches and returns web content. 'proprietary' uses Valyu's full-text multimodal indicies (arxiv/pubmed/proprietary academic content). 'news' searches and returns only news articles. |
| `fast_mode` | boolean | No | Enable fast mode for reduced latency but shorter results. Best for general purpose queries. |
| `max_price` | number<float> | No | Maximum price in dollars for a thousand retrievals (CPM). Only applies when provided. If not provided, adjusts automatically based on search type and max number of results. |
| `relevance_threshold` | number<float> | No | Minimum relevance score for results (0.0-1.0) |
| `included_sources` | string[] | No | List of specific sources to search (URLs, domains or dataset names). When a URL or domain path is provided (e.g., 'https://valyu.ai/blog' or 'valyu.ai/blog'), only that specific path will be searched. For entire domains, use either the domain name (e.g., 'valyu.ai') or the base URL (e.g., 'https://valyu.ai'). |
| `excluded_sources` | string[] | No | List of specific sources to exclude from search (URLs, domains, or dataset names). When a URL or domain path is provided (e.g., 'https://valyu.ai/blog' or 'valyu.ai/blog'), only that specific path will be excluded. For entire domains, use either the domain name (e.g., 'valyu.ai') or the base URL (e.g., 'https://valyu.ai'). |
| `category` | string | No | Natural language category/guide phrase to help guide the search to the most relevant content. For example 'agentic use-cases |
| `response_length` | default:short | No | Controls the length of content returned per result. Can be an integer for character count or predefined values: 'short' (25k), 'medium' (50k), 'large' (100k), 'max' (full) |
| `country_code` | string | No | 2-letter ISO country code to bias search results to a specific country |
| `is_tool_call` | boolean | No | Tunes retrieval process based on whether the API is being called by an AI agent as a tool call, or a user query. |
| `start_date` | string<date> | No | Start date for time-filtered searches (YYYY-MM-DD) |
| `end_date` | string<date> | No | End date for time-filtered searches (YYYY-MM-DD) |
| `url_only` | boolean | No | When set to true, only returns URLs for results (no content). Only applies when search_type is 'web' or 'news'. |

```bash
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"valyu","path":"/v1/search","body":{"query":"<string>","max_num_results":"<integer>","search_type":"<string>","fast_mode":"<boolean>","max_price":"<number>","relevance_threshold":"<number>","included_sources":"<string>","excluded_sources":"<string>","category":"<string>","response_length":"<string>","country_code":"<string>","is_tool_call":"<boolean>","start_date":"<string>","end_date":"<string>","url_only":"<boolean>"}}'
```

### Answer

Reference for the Valyu Answer endpoint that blends search results into AI-generated answers via POST /v1/answer.

`POST /v1/answer`

**Estimated cost:** $0.01

**Docs:** https://docs.valyu.ai/api-reference/endpoint/answer

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | The search query |
| `system_instructions` | string | No | Custom instructions for AI processing |
| `structured_output` | object | No | JSON schema for structured output. When provided, enables JSON mode and returns structured data |
| `search_type` | string | No | Type of search to perform |
| `fast_mode` | boolean | No | Enable fast mode for reduced latency but shorter results. Best for general purpose queries. |
| `data_max_price` | number | No | Maximum price in dollars for data retrieval (search costs only, does not affect AI costs) |
| `included_sources` | string[] | No | List of specific sources to search (URLs, domains or dataset names). When a URL or domain path is provided (e.g., 'https://valyu.ai/blog' or 'valyu.ai/blog'), only that specific path will be searched. For entire domains, use either the domain name (e.g., 'valyu.ai') or the base URL (e.g., 'https://valyu.ai'). |
| `excluded_sources` | string[] | No | List of specific sources to exclude from search (URLs, domains, or dataset names). When a URL or domain path is provided (e.g., 'https://valyu.ai/blog' or 'valyu.ai/blog'), only that specific path will be excluded. For entire domains, use either the domain name (e.g., 'valyu.ai') or the base URL (e.g., 'https://valyu.ai'). |
| `start_date` | string | No | Start date filter (YYYY-MM-DD) |
| `end_date` | string | No | End date filter (YYYY-MM-DD) |
| `country_code` | string | No | 2-letter ISO country code to bias search results to a specific country |
| `streaming` | boolean | No | Enable Server-Sent Events (SSE) streaming. When true, returns a stream of chunks: search_results first, then content deltas, then metadata, then [DONE]. |

```bash
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"valyu","path":"/v1/answer","body":{"query":"<string>","system_instructions":"<string>","structured_output":"<object>","search_type":"<string>","fast_mode":"<boolean>","data_max_price":"<number>","included_sources":"<string>","excluded_sources":"<string>","start_date":"<string>","end_date":"<string>","country_code":"<string>","streaming":"<boolean>"}}'
```

### Contents

Reference for the Valyu Contents endpoint that extracts clean, structured content from any URL via POST /v1/contents.

`POST /v1/contents`

**Estimated cost:** $0.01

**Docs:** https://docs.valyu.ai/api-reference/endpoint/contents

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `urls` | string[] | Yes | List of URLs to process (maximum 10 URLs per request) |
| `response_length` | default:short | No | Content length configuration: "short": 25,000 characters (good for summaries) "medium": 50,000 characters (good for articles) "large": 100,000 characters (good for academic papers) "max": No character limit Custom integer: Specific character limit |
| `max_price_dollars` | number | No | Maximum cost limit in dollars for the entire request. If not specified, defaults to 2x the estimated cost. |
| `extract_effort` | string | No | Processing effort level: "normal": Fastest extraction speed (Fastest) "high": Enhanced extraction with better content quality and reliability (Slower) "auto": Automatically chooses the right effort level (Slowest) |
| `screenshot` | boolean | No | Request page screenshots. When true, each result will include a screenshot_url field containing a pre-signed URL to a screenshot image of the page. Screenshots are captured during page rendering. |
| `summary` | boolean | No | Toggle AI processing (false is default) |

```bash
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"valyu","path":"/v1/contents","body":{"urls":"<string>","response_length":"<string>","max_price_dollars":"<number>","extract_effort":"<string>","screenshot":"<boolean>","summary":"<boolean>"}}'
```

### Create Batch

Reference for creating a new batch via POST /v1/deepresearch/batches.

`POST /v1/deepresearch/batches`

**Estimated cost:** $0.01

**Docs:** https://docs.valyu.ai/api-reference/endpoint/deepresearch-batch-create

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | No | Optional name for the batch |
| `mode` | enum<string> | No | DeepResearch mode for all tasks in this batch |
| `output_formats` | (string | object)[] | No | Default output formats for all tasks (markdown, pdf, toon, or structured JSON schema). Cannot mix JSON schema with markdown/pdf. toon requires a JSON schema. |
| `search` | object | No | Search configuration applied to all tasks in the batch (cannot be overridden per task) |
| `webhook_url` | string<uri> | No | HTTPS URL to receive notifications when the batch completes |
| `metadata` | object | No | Custom metadata for tracking and organization |

```bash
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"valyu","path":"/v1/deepresearch/batches","body":{"name":"<string>","mode":"<string>","output_formats":"<object>","search":"<object>","webhook_url":"<string>","metadata":"<object>"}}'
```

### Create Task

Reference for creating a new deep research task via POST /v1/deepresearch/tasks.

`POST /v1/deepresearch/tasks`

**Estimated cost:** $0.01

**Docs:** https://docs.valyu.ai/api-reference/endpoint/deepresearch-create

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Research query or task description |
| `mode` | string | No | DeepResearch mode: fast: Ideal for quicker answers and lightweight research. Typically completes in ~2–5 minutes. standard: A balanced option for deeper insights without long wait times. Runs for ~10–20 minutes. heavy: Designed for in-depth, long-running research tasks. Can run for up to ~90 minutes. |
| `model` | string | No | DeepResearch mode (deprecated, use 'mode' instead) |
| `output_formats` | string | No | Output formats. Use ['markdown'], ['markdown', 'pdf'], or a JSON schema object for structured output. Cannot mix JSON schema with markdown/pdf. |
| `strategy` | string | No | Natural language strategy instructions prepended to the system prompt |
| `search` | object | No | Search configuration parameters |
| `urls` | string[] | No | URLs to extract content from (max 10) |
| `files` | object[] | No | File attachments (PDFs, images, documents). Max 10 files. |
| `mcp_servers` | object[] | No | MCP server configurations for custom tools (max 5 servers) |
| `code_execution` | boolean | No | Enable/disable code execution during research |
| `previous_reports` | string[] | No | Previous deep research IDs to use as context (max 3) |
| `webhook_url` | string | No | HTTPS URL for webhook notifications. When provided, Valyu will POST the full task result to this URL when the task completes or fails. The request includes X-Webhook-Signature and X-Webhook-Timestamp headers for verification. HTTP URLs are rejected—only HTTPS is supported. |
| `metadata` | object | No | Custom metadata for tracking |
| `deliverables` | object[] | No | Additional file outputs to generate from the research (CSV, Excel, PowerPoint, Word, PDF). Max 10 deliverables. |

```bash
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"valyu","path":"/v1/deepresearch/tasks","body":{"query":"<string>","mode":"<string>","model":"<string>","output_formats":"<string>","strategy":"<string>","search":"<object>","urls":"<string>","files":"<object>","mcp_servers":"<object>","code_execution":"<boolean>","previous_reports":"<string>","webhook_url":"<string>","metadata":"<object>","deliverables":"<object>"}}'
```

### Add Tasks to Batch

Reference for adding tasks to a batch via POST /v1/deepresearch/batches//tasks.

`POST /v1/deepresearch/batches/{id}/tasks`

**Estimated cost:** $0.01

**Docs:** https://docs.valyu.ai/api-reference/endpoint/deepresearch-batch-add-tasks

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `tasks` | object[] | Yes | Array of tasks to add to the batch (1-100 tasks per request) |

```bash
# Replace {id} in "path" with real values before sending
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"valyu","path":"/v1/deepresearch/batches/{id}/tasks","body":{"tasks":"<object>"}}'
```

---

Full details and an interactive quickstart: https://orthogonal.com/discover/valyu