---
title: ScaleDown
description: "Use ScaleDown's Decisions and Extract APIs with the AI SDK."
url: "https://ai-sdk.dev/providers/ai-sdk-providers/scaledown"
docs_index: /llms.txt
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

The [ScaleDown](https://scaledown.ai) provider answers choice, boolean, and score
questions with ScaleDown's classification model through its
[Decisions API](https://docs.scaledown.ai/api-reference/decisions), and extracts
text fields and lists through its [Extract API](https://docs.scaledown.ai/api-reference/extract).

## Setup

Install the provider:

```sh
pnpm add @ai-sdk/scaledown
```

Set the `SCALEDOWN_API_KEY` environment variable, or configure an instance:

```ts
import { createScaleDown } from '@ai-sdk/scaledown';

const scaledown = createScaleDown({ apiKey: 'your-api-key' });
```

`createScaleDown` also accepts `baseURL` (default `https://api.scaledown.xyz`),
`headers`, and a custom `fetch` implementation. Authentication uses `x-api-key`.

## Decision Models

```ts
import { scaledown } from '@ai-sdk/scaledown';
import { experimental_decide } from 'ai';

const result = await experimental_decide({
  model: scaledown.decisionModel('classify-1'),
  state: 'The export button crashes in Safari. It works in Chrome.',
  questions: {
    category: {
      type: 'choice',
      criteria: {
        bug: 'Broken functionality',
        feedback: 'Product suggestions',
      },
    },
    hasWorkaround: {
      type: 'boolean',
      instructions: 'Can the user work around this issue?',
    },
    severity: {
      type: 'score',
      instructions: 'How severe is the reported issue?',
      criteria: ['Cosmetic', 'Degraded, with a workaround', 'Blocking'],
    },
  },
});

console.log(result.answers);
console.log(result.usage);
```

The provider sends one request to `POST /v1/scaledown`. ScaleDown evaluates each
question against the shared state and aggregates token usage across those calls.

| Model        | Choice | Boolean | Score | Box | Image/PDF Input |
| ------------ | ------ | ------- | ----- | --- | --------------- |
| `classify`   | ✓      | ✓       | ✓     | ✗   | ✓               |
| `classify-1` | ✓      | ✓       | ✓     | ✗   | ✓               |

`classify` selects the latest version; `classify-1` pins version 1. Other model
IDs are forwarded to ScaleDown for validation.

- Choice questions select one option and return its complete probability distribution.
  Null option descriptions use the option name.
- Boolean questions map to ScaleDown's `noul` primitive and return `P(true)`.
  Boolean criteria are included in the native question's instructions.
- Score questions require 2–10 non-null, ordered levels. Scores are zero-based,
  probability-weighted means and can be fractional.

Text parts are joined with newlines. JSON state and structured instructions or
criteria are serialized to text, preserving fields that ScaleDown would otherwise
ignore. State can also contain one JPEG, PNG, TIFF, or PDF file part; the provider
sends it as a base64-encoded document alongside any text.

The Decisions API does not support `reasoning`, `maxOutputTokens`, or provider
options; supplying them produces warnings.

### Provider Metadata

`result.providerMetadata.scaledown` contains `confidence` and `legend` maps keyed by
question ID, plus the total request `cost` in USD when supplied by ScaleDown. The
package exports `ScaleDownDecisionProviderMetadata` for typed access.

### Classify and Decisions

ScaleDown's [`/classify` and Decisions APIs](https://docs.scaledown.ai/api-reference/classify-overview)
use the same scoring model with different request and response shapes.
`/classify` accepts labels with rubrics; Decisions accepts typed questions and
returns one answer per question. This provider implements the Decisions endpoint.
Classify-specific batching, multi-label settings, and free-form reasoning are
available through ScaleDown's separate `/classify` API.

## Extraction Models

Use `experimental_extract` with `scaledown.extractionModel`:

```ts
import { scaledown } from '@ai-sdk/scaledown';
import { experimental_extract } from 'ai';

const result = await experimental_extract({
  model: scaledown.extractionModel('extract-1'),
  state: 'Invoice INV-2041 from Acme Corp. Contacts: Ana, Bo.',
  fields: {
    invoiceNumber: { type: 'text', instructions: 'The invoice number' },
    vendor: { type: 'text', instructions: 'Company that issued the invoice' },
    contacts: { type: 'list', items: 'text', instructions: 'Contact names' },
  },
  providerOptions: { scaledown: { threshold: 0.5 } },
});

console.log(result.answers);
console.log(result.usage);
```

The provider calls `POST /v1/chat/completions` using a JSON schema for the fields.
`extract` selects the latest model; `extract-1` pins version 1. Both support text
and text-list fields, with the same text, JSON, and single-document inputs as
decision models.

For document-only input, the provider supplies the non-empty user message
required by ScaleDown automatically.

- Text fields return the most confident verbatim match, or `null` if none is found.
- Text lists return up to 30 distinct matches in source order, or `null`
  when none are found. Each item retains its confidence and source when available.
- Text sources convert ScaleDown's byte offsets to UTF-16 offsets in the original
  state part. JSON parts have no source location. Document matches cite the file
  when their location can be established; OCR text is available in
  `result.providerMetadata.scaledown.ocrText`.

ScaleDown extracts spans rather than normalizing values. Number, date, time,
datetime, duration, and lists of numbers or dates are unsupported and throw an
error. To retrieve amounts or dates verbatim, use text fields.

The optional `providerOptions.scaledown.threshold` sets the minimum confidence
from 0 to 1 (default 0). The package exports
`Experimental_ScaleDownExtractionModelOptions` for this setting.
`referenceDate`, `reasoning`, and `maxOutputTokens` are unsupported and produce
warnings. ScaleDown does not return `pNull` or guesses; the provider leaves them
unset.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)