# Riveter 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)

Power your product with data from the web. Riveter's agents manage web search, scraping, browser infrastructure, and proxies for you. Every result has a source.

**Verified:** yes

## 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

### Scrape

Scrape a webpage and return the text content. This endpoint allows you to extract text content from any public webpage.

`POST /v1/scrape`

**Estimated cost:** Dynamic — use `"dryRun": true` in the Run API request to check the exact cost before calling.

**Docs:** https://docs.riveterhq.com/#tag/tools/post/scrape

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Example: "https://example.com" |
| `proxy_country_code` | string | No | Optional two-character country code for proxy (e.g., 'us', 'gb', 'de') |
| `skip_cache` | boolean | No | Default: false. Set to true to bypass cache and always fetch fresh content |

```bash
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"riveter","path":"/v1/scrape","body":{"url":"<string>","proxy_country_code":"<string>","skip_cache":"<boolean>"}}'
```

### Run

Copy link Define the structure of your output directly in the API request. This endpoint allows you to define both your input data and output configuration in a single request.

`POST /v1/run`

**Estimated cost:** Dynamic — use `"dryRun": true` in the Run API request to check the exact cost before calling.

**Docs:** https://docs.riveterhq.com/#tag/run-from-configuration/post/run

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `input` | object | Yes | The input object contains your source data:  Keys are column/attribute names Values are arrays of strings (all arrays must be the same length) Maximum 1000 rows per request |
| `output` | object | Yes | The output object defines what data you want to extract:  Keys are the names of attributes you want to extract Each attribute requires: prompt: Instructions for finding/extracting this data contexts: Array of input or other output attribute names this depends on. Optional Output Configuration Each output attribute can optionally include:  format: Data type ('number', 'json', 'url', 'text', 'email', 'tag', 'date', 'boolean') format_details: Format-specific configuration (varies by format type). For json format, you can provide either a description (string) or a schema (JSON Schema object) or both. tools: Array of tools to use (['web_search', 'web_scrape', 'query_pdf', 'query_image']) max_tool_calls: Number of tool calls allowed (0-10) run_when: When to run this extraction ('always', 'any_filled', 'all_filled') |
| `run_key` | string | No | Custom identifier for this run (optional, will be generated if not provided) |

```bash
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"riveter","path":"/v1/run","query":{"run_key":"<string>"},"body":{"input":"<object>","output":"<object>"}}'
```

### Run status

Check the current status of a project run

`GET /v1/run_status`

**Cost:** Free

**Docs:** https://docs.riveterhq.com/#tag/runs/get/run_status

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `run_key` | string | Yes | The run key (UUID) of the project run to check |

```bash
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"riveter","path":"/v1/run_status","method":"GET","query":{"run_key":"<string>"}}'
```

### Run data

Retrieve the processed data from a completed project run

`GET /v1/run_data`

**Cost:** Free

**Docs:** https://docs.riveterhq.com/#tag/runs/get/run_data

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `run_key` | string | Yes | The run key (UUID) of the project run to retrieve data for |

```bash
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"riveter","path":"/v1/run_data","method":"GET","query":{"run_key":"<string>"}}'
```

### Stop run

Stop a currently running project. This will halt all processing and mark the run as stopped. Behavior:  If the run is already stopped or success, returns success with current status. If the run is in progress, stops all pending cells and marks the run as stopped.  Stopped runs cannot be resumed

`POST /v1/stop_run`

**Cost:** Free

**Docs:** https://docs.riveterhq.com/#tag/runs/post/stop_run

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `run_key` | string | Yes | The run key (UUID) of the project run to stop |

```bash
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"riveter","path":"/v1/stop_run","query":{"run_key":"<string>"}}'
```

---

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