# Runs

> Run a method with your own input, or send a query and get the result.

Source: https://docs.fous.com/api-reference/runs
Index: https://docs.fous.com/llms.txt

- `POST /v1/runs`: Run a method or a query
- `GET /v1/runs/{id}`: Get a run
- `POST /v1/runs/{id}/cancel`: Cancel a run

## The Run object

- `id` (string, required): run_ followed by 26 characters; results are kept 24 hours.
- `status` (string, required): partial (query): an answer, but not all of what was asked. One of `running`, `completed`, `partial`, `failed`.
- `method` (object): The method and the version that ran.
  - `id` (string)
  - `slug` (string or null)
  - `version` (integer)
  - `latest_version` (integer): POST /v1/runs: the method’s newest version.
- `data` (JSON value): The result, shaped by the method’s output_schema (query: by your output_schema when you send one).
- `notice` (string): A completed run that came back empty or incomplete while the version is under repair: it cost nothing, and when the repair is back at the latest.
- `empty` (boolean): The site answered and has nothing for this input (still a success).
- `raw` (JSON value): With include_raw: the site’s own response.
- `truncated` (boolean): The answer is not complete: the site had more than the run could read, or the output was over 10 MB and its longest list was cut. missing says what.
- `missing` (array of string): What the answer lacks, in plain words (a source that failed, items that could not be read, pages not read). Only when something is.
- `cost` (object)
  - `credits` (integer)
- `duration_ms` (integer)
- `source` (string): query: methods answered, or a live web search did. One of `methods`, `live`.
- `steps` (array of object): query: the method calls made (method: id, slug and the version that ran) and their status.
- `sources` (array of object): query, live answers: the pages the data came from.
- `uncovered` (array of string): query: the things asked for that no method provides yet, answered from the live web beside the method calls.
- `created_at` (string): running only.

```json
{
  "id": "run_01m5m0ere4fzdte37jhhn33ycd",
  "status": "completed",
  "method": {
    "id": "mth_01m5kvvywdeac8fxs7nh0sw68w",
    "slug": "date.nager.at/list_public_holidays",
    "version": 2,
    "latest_version": 2
  },
  "data": {
    "country_name": "Germany",
    "year": 2027,
    "holidays": [
      {
        "date": "2027-01-01",
        "weekday": "Friday",
        "english_name": "New Year's Day",
        "local_name": "Neujahr",
        "nationwide": "yes",
        "regions": [],
        "type": "Public"
      },
      {
        "date": "2027-01-06",
        "weekday": "Wednesday",
        "english_name": "Epiphany",
        "local_name": "Heilige Drei Könige",
        "nationwide": "no",
        "regions": [
          "Baden-Württemberg",
          "Bavaria",
          "Saxony-Anhalt"
        ],
        "type": "Public"
      }
    ]
  },
  "truncated": false,
  "cost": {
    "credits": 1
  },
  "duration_ms": 1751
}
```

## Run a method or a query

`POST https://api.fous.com/v1/runs`

Two ways to run. With method (manual): runs that method with inputs that fit its input_schema (1 credit). With query (auto): Fous finds read methods, fills their inputs, runs up to three and returns the data, shaped by output_schema when you send one; when no method fits, it answers from the live web (source "live", sources named). A query costs 5 credits, nothing when it has no answer (404 not_found with run_id); status is partial when not all of what was asked was found; one the request check turns away answers 422 request_refused. Both wait up to wait seconds (default 30). A run still going then answers 202 with status "running" and goes on: read it with GET /v1/runs/{id}, or stop it with POST /v1/runs/{id}/cancel (nothing is charged). A query ends within 3 minutes. Hanging up before any answer stops a query; after a 202 it goes on.

### Request body

Required, JSON. One of:

#### Run a method

- `method` (string, required): The method’s id (mth_…) or slug (<domain>/<name>); add @N to run version N instead of the one your organization uses (its first run sets it).
- `input` (object): Fits the method’s input_schema; an input sent as null counts as not sent.
- `connection` (string): A conn_ id, when the method needs an account and you want one other than the default.
- `include_raw` (boolean): Also return the site’s own response as raw.
- `wait` (integer): Seconds to wait for the answer, 0 to 60 (default 30); a longer run answers 202 and goes on.

#### Send a query

- `query` (string, required): The data you want, in plain words.
- `output_schema` (object): A JSON Schema object (type object) for the answer’s shape.
- `platform` (string): Limit it to one site.
- `wait` (integer): Seconds to wait for the answer, 0 to 60 (default 30); a longer query answers 202 and goes on.

### Returns

A [Run](https://docs.fous.com/api-reference/runs.md#the-run-object) object.

- `200`: Completed (data may be empty: true when the site has nothing).
- `202`: Still running. The same Run, with status "running".

### Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_request` | Both or neither of method and query, a body that does not fit, or an output_schema that is not an object |
| 402 | `insufficient_credits` | Not enough credits |
| 403 | `connection_required` | The method needs a connected account |
| 404 | `not_found` | No such method or version, or a query that found no answer (with run_id and steps) |
| 422 | `invalid_input`, `request_refused` | The input does not fit (invalid_input), or the request check turned a query away (request_refused) |
| 429 | `rate_limited` | Too many requests |
| 503 | `method_repairing`, `upstream_error`, `upstream_blocked`, `upstream_timeout`, `service_unavailable` | The site failed, refused the request or did not answer in time (upstream_error, upstream_blocked, upstream_timeout), the version is under repair (method_repairing, with Retry-After), or billing is briefly unavailable (service_unavailable) |

### Example request: Run a method

```bash
curl 'https://api.fous.com/v1/runs' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "method": "date.nager.at/list_public_holidays",
    "input": {
      "country": "DE",
      "year": 2027
    }
  }'
```

With every optional parameter:

```bash
curl 'https://api.fous.com/v1/runs' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "method": "date.nager.at/list_public_holidays",
    "input": {
      "country": "DE",
      "year": 2027
    },
    "connection": "conn_01m5k2v8c4n6p8r0t2w4y6a8c0",
    "include_raw": true,
    "wait": 30
  }'
```

### Example request: Send a query

```bash
curl 'https://api.fous.com/v1/runs' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Which public holidays does Germany have in 2027?"
  }'
```

With every optional parameter:

```bash
curl 'https://api.fous.com/v1/runs' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Which public holidays does Germany have in 2027?",
    "output_schema": {
      "type": "object",
      "properties": {
        "country_name": {
          "type": "string"
        },
        "year": {
          "type": "integer"
        },
        "holidays": {
          "type": "array",
          "items": {
            "type": "object"
          }
        }
      }
    },
    "platform": "crates.io",
    "wait": 30
  }'
```

### Response 200

```json
{
  "id": "run_01m5m0ere4fzdte37jhhn33ycd",
  "status": "completed",
  "method": {
    "id": "mth_01m5kvvywdeac8fxs7nh0sw68w",
    "slug": "date.nager.at/list_public_holidays",
    "version": 2,
    "latest_version": 2
  },
  "data": {
    "country_name": "Germany",
    "year": 2027,
    "holidays": [
      {
        "date": "2027-01-01",
        "weekday": "Friday",
        "english_name": "New Year's Day",
        "local_name": "Neujahr",
        "nationwide": "yes",
        "regions": [],
        "type": "Public"
      },
      {
        "date": "2027-01-06",
        "weekday": "Wednesday",
        "english_name": "Epiphany",
        "local_name": "Heilige Drei Könige",
        "nationwide": "no",
        "regions": [
          "Baden-Württemberg",
          "Bavaria",
          "Saxony-Anhalt"
        ],
        "type": "Public"
      }
    ]
  },
  "truncated": false,
  "cost": {
    "credits": 1
  },
  "duration_ms": 1751
}
```

### Response 202

```json
{
  "id": "run_01m5m0ere4fzdte37jhhn33ycd",
  "status": "running",
  "method": {
    "id": "mth_01m5kvvywdeac8fxs7nh0sw68w",
    "slug": "date.nager.at/list_public_holidays",
    "version": 2,
    "latest_version": 2
  },
  "created_at": "2026-10-23T09:11:15.035Z"
}
```

### Error 400

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Send either method (with its input) or query, not both.",
    "doc_url": "https://docs.fous.com/guides/errors#invalid_request",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}
```

## Get a run

`GET https://api.fous.com/v1/runs/{id}`

Status and result of a run (a method’s or a query’s), kept 24 hours. Free. A failed run answers with its own status and error, which carries run_id (and for a query its steps).

### Path parameters

- `id` (string, required)

### Query parameters

- `wait` (integer): Seconds to hold the answer while it is still running, 0 to 60. Default 0.

### Returns

A [Run](https://docs.fous.com/api-reference/runs.md#the-run-object) object.

- `200`: Finished.
- `202`: Still running. The same Run, with status "running".

### Errors

| Status | Code | When |
| --- | --- | --- |
| 403 | `connection_required` | The run needed a connected account |
| 404 | `not_found` | Unknown or expired, or a query that found no answer (with its run_id) |
| 409 | `conflict` | The run was stopped (reason stopped) |
| 422 | `invalid_input` | The site refused the input |
| 503 | `upstream_error`, `upstream_blocked`, `upstream_timeout`, `method_unavailable` | The site failed, refused the request or did not answer in time (upstream_error, upstream_blocked, upstream_timeout), or the method is broken (method_unavailable) |

### Example request

```bash
curl 'https://api.fous.com/v1/runs/run_01m5m0ere4fzdte37jhhn33ycd' \
  -H "Authorization: Bearer $FOUS_API_KEY"
```

With every optional parameter:

```bash
curl 'https://api.fous.com/v1/runs/run_01m5m0ere4fzdte37jhhn33ycd?wait=30' \
  -H "Authorization: Bearer $FOUS_API_KEY"
```

### Response 200

```json
{
  "id": "run_01m5m0ere4fzdte37jhhn33ycd",
  "status": "completed",
  "method": {
    "id": "mth_01m5kvvywdeac8fxs7nh0sw68w",
    "slug": "date.nager.at/list_public_holidays",
    "version": 2,
    "latest_version": 2
  },
  "data": {
    "country_name": "Germany",
    "year": 2027,
    "holidays": [
      {
        "date": "2027-01-01",
        "weekday": "Friday",
        "english_name": "New Year's Day",
        "local_name": "Neujahr",
        "nationwide": "yes",
        "regions": [],
        "type": "Public"
      },
      {
        "date": "2027-01-06",
        "weekday": "Wednesday",
        "english_name": "Epiphany",
        "local_name": "Heilige Drei Könige",
        "nationwide": "no",
        "regions": [
          "Baden-Württemberg",
          "Bavaria",
          "Saxony-Anhalt"
        ],
        "type": "Public"
      }
    ]
  },
  "truncated": false,
  "cost": {
    "credits": 1
  },
  "duration_ms": 1751
}
```

### Response 202

```json
{
  "id": "run_01m5m0ere4fzdte37jhhn33ycd",
  "status": "running",
  "created_at": "2026-10-23T09:11:15.035Z"
}
```

### Error 403

```json
{
  "error": {
    "code": "connection_required",
    "message": "Your notion.so account is no longer signed in. The site sent the request to its sign-in page.",
    "next_step": "Sign in at connect_url (a Fous Studio page), or with POST /v1/connections/conn_01m5k2v8c4n6p8r0t2w4y6a8c0/sign-in, then run again. Nothing was charged.",
    "connect": {
      "platform": "notion.so",
      "type": "session",
      "connection_id": "conn_01m5k2v8c4n6p8r0t2w4y6a8c0"
    },
    "connect_url": "https://app.fous.com/org_01M4CD7TVHDBPFQHZD05XMW5PB/connections?connect=conn_01m5k2v8c4n6p8r0t2w4y6a8c0",
    "run_id": "run_01m5m0ere4fzdte37jhhn33ycd",
    "doc_url": "https://docs.fous.com/guides/errors#connection_required",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}
```

## Cancel a run

`POST https://api.fous.com/v1/runs/{id}/cancel`

Cancels a run (a method’s or a query’s) that is still going: nothing is charged, reading it afterwards answers 409 conflict with reason "stopped", and what the site answers after that is dropped. Free.

### Path parameters

- `id` (string, required)

### Returns

- `200`: Stopped.

The answer has these fields:

- `id` (string)
- `stopped` (boolean)

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `not_found` | Unknown or expired |
| 409 | `conflict` | Already ended |

### Example request

```bash
curl 'https://api.fous.com/v1/runs/run_01m5m0ere4fzdte37jhhn33ycd/cancel' \
  -X POST \
  -H "Authorization: Bearer $FOUS_API_KEY"
```

### Response 200

```json
{
  "id": "run_01m5m0ere4fzdte37jhhn33ycd",
  "stopped": true
}
```

### Error 404

```json
{
  "error": {
    "code": "not_found",
    "message": "No such run.",
    "doc_url": "https://docs.fous.com/guides/errors#not_found",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}
```