# Run a query

> Send a query in plain language and get the result. Fous picks the methods, fills their inputs and runs them.

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

Send `POST /v1/runs` a `query` instead of a `method`. Fous finds the methods that fit, fills their inputs, runs up to three and returns one result.

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

```json
{
  "id": "run_01m5m1a2b3c4d5e6f7g8h9j0kq",
  "status": "completed",
  "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,
  "steps": [
    {
      "method": {
        "id": "mth_01m5kvvywdeac8fxs7nh0sw68w",
        "slug": "date.nager.at/list_public_holidays",
        "version": 2
      },
      "input": { "country": "DE", "year": 2027 },
      "status": "completed"
    }
  ],
  "source": "methods",
  "cost": { "credits": 5 },
  "duration_ms": 4120
}
```

| Field | Meaning |
| --- | --- |
| `query` | What you want, 3 to 2,000 characters, with the values that matter. |
| `output_schema` | Optional. A JSON Schema object; `data` comes back in that shape. |
| `platform` | Optional. The one site to answer from. |
| `wait` | Optional. Seconds to wait, 0 to 60, 30 by default. |

## The result

- `steps`: each method call, with the version and the input Fous chose.
- `source`: `methods`, or `live` when the answer came from the live web, with its pages in `sources`.
- `uncovered`: parts no method covers yet, answered from the live web.
- `status: "partial"`: part is missing. `empty: true`: the named site has nothing.

A slow query answers `202` and is read or cancelled by `id`, like a [slow run](https://docs.fous.com/guides/runs.md#slow-runs).

## When there is no result

A query with no result is free and fails with the `steps` it tried:

```json
{
  "error": {
    "code": "not_found",
    "message": "No method fits this request and no live source had the answer.",
    "next_step": "Try other words, name the website with platform, or build a method with POST /v1/builds. Nothing was charged.",
    "steps": [],
    "source": "live",
    "run_id": "run_01m5m1a2b3c4d5e6f7g8h9j0kq",
    "doc_url": "https://docs.fous.com/guides/errors#not_found",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}
```

It can also fail with `403 connection_required` when the methods that fit need an [account](https://docs.fous.com/guides/connections.md). A query never builds: send the request to [`POST /v1/builds`](https://docs.fous.com/guides/builds.md) to make the missing method.

## Query or run?

[Run a method](https://docs.fous.com/guides/runs.md) when you know which one: its output follows its schema and costs 1 credit, not 5. Send a query when you do not know the method, need calls chained, or want your own shape.