> ## Documentation Index
> Fetch the complete documentation index at: https://outcrawl.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Models

> Name a model for each job Scout does, on any endpoint that speaks the chat completions API.

export const OutcrawlStyles = () => {
  if (typeof document !== 'undefined' && !document.getElementById('outcrawl-overrides')) {
    const s = document.createElement('style');
    s.id = 'outcrawl-overrides';
    s.textContent = `
      /* Match the product's radius grid (4 / 6 / 8 / 9999), not Mintlify's default. */
      .rounded-sm { border-radius: 0.375rem !important; } /* 6px, --r-ctl */
      .rounded-md { border-radius: 0.375rem !important; } /* 6px, --r-ctl */
      .rounded-lg { border-radius: 0.5rem !important; }   /* 8px, --r-panel */
      .rounded-l-sm { border-top-left-radius: 0.375rem !important; border-bottom-left-radius: 0.375rem !important; }
      .rounded-r-sm { border-top-right-radius: 0.375rem !important; border-bottom-right-radius: 0.375rem !important; }
      .rounded-l-md { border-top-left-radius: 0.375rem !important; border-bottom-left-radius: 0.375rem !important; }
      .rounded-r-md { border-top-right-radius: 0.375rem !important; border-bottom-right-radius: 0.375rem !important; }
      .rounded-l-lg { border-top-left-radius: 0.5rem !important; border-bottom-left-radius: 0.5rem !important; }
      .rounded-r-lg { border-top-right-radius: 0.5rem !important; border-bottom-right-radius: 0.5rem !important; }

      /* Cards: never pure white in light mode, matching the one-big-card surface tone. */
      .card { background-color: #fcfcfc !important; border-radius: 0.5rem !important; }
      html.dark .card { background-color: #141311 !important; }

      /* Docs hero box */
      .oc-hero { background-color: #fcfcfc; border: 1px solid #e5e2dc; }
      html.dark .oc-hero { background-color: #141311; border-color: #26241f; }
      html.dark .oc-hero h1 { color: #edeae4; }

      /* Thin, transparent-track, hide-until-hover scrollbar. */
      ::-webkit-scrollbar { width: 6px; height: 6px; background-color: transparent; }
      ::-webkit-scrollbar-track { background-color: transparent; }
      ::-webkit-scrollbar-thumb { background-color: rgba(155, 155, 155, 0.5); border-radius: 10px; transition: opacity 0.3s ease; opacity: 0; }
      ::-webkit-scrollbar-thumb:hover { background-color: rgba(155, 155, 155, 0.7); }
      *:hover::-webkit-scrollbar-thumb,
      *:focus::-webkit-scrollbar-thumb,
      *:active::-webkit-scrollbar-thumb { opacity: 1; }
      * { scrollbar-width: thin; scrollbar-color: rgba(155, 155, 155, 0.5) transparent; }
    `;
    document.head.appendChild(s);
  }
  return null;
};

<OutcrawlStyles />

Scout has no built-in model and no default: no model id, no provider and no base URL. You name a model for each job you use, on any endpoint that speaks the chat completions API (`POST /chat/completions`): a hosted provider, a gateway, or a server on your own machine. Each job can use its own endpoint and its own key.

```ts theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
const scout = new Scout({
  browser: 'outcrawl',
  models: {
    hands: { model: 'your-fast-model', baseURL: urlA, apiKey: keyA },
    brain: { model: 'your-strong-model', baseURL: urlB, apiKey: keyB, effort: 'low' },
    eyes: { model: 'your-vision-model', baseURL: urlA, apiKey: keyA },
    extract: { model: 'your-local-model', baseURL: localUrl, apiKey: '' },
  },
});
```

## The jobs

| Job | What it does | What matters |
| - | - | - |
| `hands`, required | Reads the page's accessibility tree and picks each action: click, type, scroll, navigate, read. | Called on every step, so it sets most of a run's speed and cost. A fast model that follows a JSON schema reliably. |
| `brain`, optional | Decides every step from a compact view of the page and the run so far; `hands` carries the decision out. | Helps long tasks that cross several pages or need a plan. A stronger reasoning model. |
| `eyes`, optional | Answers questions about a screenshot when the agent asks to look at the page. | Must accept images. Without it the agent works from the accessibility tree alone. |
| `extract`, optional | Reads a page into the answer or into your schema. | Long pages and exact fields. Without it `hands` extracts. |

`models` takes only these four keys and `rates`. Anything else throws `ScoutConfigError`.

## What each job takes

| Field | Required | What it is |
| - | - | - |
| `model` | yes | The model id, exactly as your endpoint expects it. |
| `baseURL` | yes | The endpoint's `http` or `https` base URL, the part before `/chat/completions`, for example `https://api.example.com/v1` or `http://localhost:11434/v1`. |
| `apiKey` | yes | Sent as a bearer token. `''` sends none, for a local server. |
| `effort` | no | How hard the model may think, for a model that takes a reasoning effort: `'minimal'`, `'low'`, `'medium'` or `'high'`. Absent sends none. |
| `structuredOutput` | no | How a JSON reply is asked for. Default `'tool_choice'`. See below. |
| `headers` | no | Extra headers sent with every request to this endpoint, as a map of header names to strings. |

### Structured replies

Scout asks each model for JSON. `structuredOutput` sets how:

* `'tool_choice'` (the default) forces one function call whose parameters are the schema. Function calling is the most widely supported way to get structured output across chat completions endpoints.
* `'json_object'` asks for any JSON and spells the schema out in the prompt, for an endpoint without function calling.
* `'strict'` sends a strict `json_schema` response format, for an endpoint that supports it.

If your endpoint refuses the mode, it answers 400 and the run's `error` names the job, its model and the two other settings to try, for example `set models.hands.structuredOutput to 'json_object' or 'strict'`. Scout does not switch modes on its own: you decide which one your endpoint takes.

## Cost

When your endpoint states a cost per call, `result.costUsd` is the run's model spend in USD. To price models yourself, and to hold a run to a [`caps.budget`](/docs/scout/runs#caps), pass `models.rates` with every job's model:

```ts theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
models: {
  hands: { ... },
  rates: {
    'your-model-id': {
      input: '0.30',
      output: '1.20',
      cacheRead: null,
      cacheWrite: null,
      inputModalities: ['text'],
    },
  },
}
```

Prices are USD per million tokens as decimal strings, keyed by model id. `cacheRead` and `cacheWrite` are `null` when the endpoint bills no such line, which is not the same as billing zero. `inputModalities` lists what the model accepts: `'text'`, and `'image'` for a model that reads screenshots. Once you pass `rates`, every job's model needs an entry, or `new Scout` throws `ScoutConfigError` rather than report a cost that reads as zero. Without rates and without a stated cost, `costUsd` is absent rather than zero.

## Models from the environment

The [examples](/docs/scout/examples) read their models from environment variables through a small helper, [`examples/models.ts`](https://github.com/outcrawlai/scout/blob/main/packages/scout/examples/models.ts). Scout itself reads none of these: the only variable it reads is `OUTCRAWL_API_KEY`, for the cloud browser. Start from the helper if the pattern suits you.

| Variable | What it sets |
| - | - |
| `SCOUT_BASE_URL` | Your endpoint's base URL, the part before `/chat/completions`. |
| `SCOUT_API_KEY` | Its key. Leave it empty for a local server that takes none. |
| `SCOUT_HANDS_MODEL` | Required: the model that reads the page and acts. |
| `SCOUT_BRAIN_MODEL` | Optional: decides each step on long, multi-page tasks. |
| `SCOUT_EYES_MODEL` | Optional: an image-capable model for questions about a screenshot. |
| `SCOUT_EXTRACT_MODEL` | Optional: reads pages into your schema. |

Any job can use its own endpoint with `SCOUT_<JOB>_BASE_URL` and `SCOUT_<JOB>_API_KEY`, for example `SCOUT_BRAIN_BASE_URL`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.