# Run a method

> Send your own input to a method, read the result, follow a slow run, cancel it, and handle failures.

Source: https://docs.fous.com/guides/runs
Index: https://docs.fous.com/llms.txt

Run a method with your own input and get its data.

```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 },
    "wait": 30
  }'
```

```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"
      }
    ]
  },
  "truncated": false,
  "cost": { "credits": 1 },
  "duration_ms": 1751
}
```

| Field | Meaning |
| --- | --- |
| `method` | Slug or id. `@N` runs version N; without it, the version your organization uses ([Versions](https://docs.fous.com/guides/methods.md#versions)). |
| `input` | Values that fit `input_schema`. A value left out or `null` takes its default. |
| `connection` | Optional. The `conn_` id to run with ([Connect an account](https://docs.fous.com/guides/connections.md)). |
| `include_raw` | Optional. `true` adds `raw`, the site's own response. |
| `wait` | Optional. Seconds to wait for the result, 0 to 60, 30 by default. |

## The result

`data` has every field of the output schema; what the site did not show is `null`, and lists are `[]`.

- `empty: true`: the site has nothing for this input. Still a success.
- `truncated: true`: the result is incomplete; `missing` says what it lacks.
- `notice`: empty or incomplete while the method is under repair, so it is free.

## Slow runs

A run not done within `wait` answers `202` and keeps going. Keep its `id`: there is no run list or webhook.

```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"
}
```

`GET /v1/runs/{id}?wait=60` returns the result when it ends. Results are kept 24 hours.

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

`POST /v1/runs/{id}/cancel` stops it. Nothing is charged.

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

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

Each `POST /v1/runs` is a new, charged run. Keep `wait` below your HTTP client's timeout and read a slow run by `id` instead of resending it.

## Methods that change something

Run a `write` method only when the person asked for that change. A failure with `may_have_run: true` may have reached the site: check before you run it again.

## Methods that need an account

A method with `auth.required: true` runs with your connection for its site. Without a working one, the run fails with `connect_url`, where a person signs in:

```json
{
  "error": {
    "code": "connection_required",
    "message": "This method needs a signed-in notion.so account; your login (conn_01m5k2v8c4n6p8r0t2w4y6a8c0) was signed out and needs to sign in again.",
    "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",
      "status": "needs_attention"
    },
    "connect_url": "https://app.fous.com/org_01M4CD7TVHDBPFQHZD05XMW5PB/connections?connect=conn_01m5k2v8c4n6p8r0t2w4y6a8c0",
    "doc_url": "https://docs.fous.com/guides/errors#connection_required",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}
```

## Failures

A failed run is free; `retryable` says whether trying again can help. [Errors and limits](https://docs.fous.com/guides/errors.md) says what to do for each code.