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

# Classify

> Sort a document into one of the categories you name, so you can choose how to parse it.

Classify reads the first pages of a document and tells you which of your categories it belongs to. Use it when one intake receives several kinds of document, and each kind needs its own parse, extraction or pipeline. If you already know the kind, skip it.

## Classify a document

Classify reads the document itself, not a parse, so send `file` or `file_url` with your categories. This request sorts one scanned file into one of three categories and waits for the answer:

```python Python theme={null}
import os
from pulse import Pulse

client = Pulse(api_key=os.environ["PULSE_API_KEY"])

job = client.classify.run(
    file_url="https://example.com/inbox/scan-0142.pdf",
    config={"classifications": [
        {"name": "invoice", "description": "A bill for goods or services"},
        {"name": "bank_statement", "description": "Account activity for one period"},
        {"name": "other"},
    ]},
)
kind = client.classify.get_result(job.classify_id).classification
print(kind)
```

```typescript TypeScript theme={null}
import { PulseClient } from "@pulse-software/sdk";

const client = new PulseClient({ apiKey: process.env.PULSE_API_KEY! });

const { classifyId } = await client.classify.run({
  fileUrl: "https://example.com/inbox/scan-0142.pdf",
  config: {
    classifications: [
      { name: "invoice", description: "A bill for goods or services" },
      { name: "bank_statement", description: "Account activity for one period" },
      { name: "other" },
    ],
  },
});
const { classification } = await client.classify.getResult({ classifyId });
console.log(classification);
```

For the call to return at once, send `async: true` and poll the job: see [Jobs and results](https://docs.runpulse.com/v2/jobs.md). Classify reads PDFs, images, TIFFs, Word and PowerPoint files, HTML pages and Excel workbooks: see [Files and limits](https://docs.runpulse.com/v2/files.md).

***

## Write your categories

`config.classifications` lists at least one category. Each has a `name`, which comes back as the answer and can appear only once, and an optional `description` of what belongs in it. Add a description when two names could be confused.

Classify always picks the best match, even when no category fits well, so add a catch-all category such as `other` for unexpected documents.

## Choose pages

By default, Classify reads the first 5 pages, or every page of a shorter document. For other pages, send `config.page_range`, such as `"1-2"` or `"3, 7-9"`.

A range past the last page is refused with a `400` before the job starts, except in a Word, PowerPoint or HTML document. That document is first turned into pages, then read like a PDF, so there the job fails instead.

In an Excel workbook, each sheet is a page, hidden sheets included. Classify reads the text of the selected sheets, up to the first 120,000 characters, rather than an image of them.

***

## Read the result

`GET /classify/{classify_id}/result` (`client.classify.get_result`) returns the answer:

```json theme={null}
{
  "classification": "bank_statement",
  "classify_id": "classify-7c3e9a14-2b6d-4f01-8e5a-c9d2b4f61a07",
  "confidence": null,
  "usage": {
    "request": { "pages_processed": 3, "credits_used": 1.5 }
  },
  "history": { "file_name": "scan-0142.pdf" }
}
```

`classification` is exactly one of the names you sent. `confidence` is always `null` for now. `usage.request.pages_processed` counts the pages Classify read.

## Route each kind

Classify returns only a name. To act on it, send the same document with the `config_id` of a saved config for that kind. This example parses invoices and bank statements with their own [parse configs](https://docs.runpulse.com/v2/saved-configs.md) and leaves others for review:

```python Python theme={null}
PARSE_CONFIGS = {
    "invoice": os.environ["INVOICE_PARSE_CONFIG_ID"],
    "bank_statement": os.environ["STATEMENT_PARSE_CONFIG_ID"],
}

config_id = PARSE_CONFIGS.get(kind)
if config_id is not None:
    parse = client.parse.run(file_url="https://example.com/inbox/scan-0142.pdf", config_id=config_id)
```

```typescript TypeScript theme={null}
const parseConfigs: Record<string, string> = {
  invoice: process.env.INVOICE_PARSE_CONFIG_ID!,
  bank_statement: process.env.STATEMENT_PARSE_CONFIG_ID!,
};

const configId = parseConfigs[classification];
if (configId !== undefined) {
  const { parseId } = await client.parse.run({
    fileUrl: "https://example.com/inbox/scan-0142.pdf",
    configId,
  });
}
```

To run several steps for each kind, map each name to a saved pipeline config and start a [pipeline](https://docs.runpulse.com/v2/pipelines.md) instead. Classify can't be a step in a pipeline, so run it first.

***

## Pricing

Classify costs 0.5 credits per page it reads, so at most 2.5 credits per document with the default of 5 pages ([Pricing](https://docs.runpulse.com/v2/pricing.md)). Each request classifies one document.

## Next steps

> [card] [Saved configs](https://docs.runpulse.com/v2/saved-configs.md)
>
> Save a config for each kind of document.

> [card] [Classify API reference](https://docs.runpulse.com/api-reference/v2/classify/run-classify.md)
>
> Every option, field and limit.


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