---
title: "Run an extractor on a collection, document, or uploaded files (synchronous)"
method: POST
path: "/extractors/{extractor_id}/run"
tags: ["Extractors"]
---

# Run an extractor on a collection, document, or uploaded files (synchronous)

`POST /extractors/{extractor_id}/run`

## Request

- Base URL: `https://h2ogpte.genai.h2o.ai/api/v1`
- URL: `https://h2ogpte.genai.h2o.ai/api/v1/extractors/{extractor_id}/run`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/h2o/apis/h2ogpte-rest-api/docs/extractors/:extractor_id/run/post.ts> (a function with typed inputs; its response is checked against the schema)

Executes the specified extractor synchronously and returns results with a 200 OK response.

Exactly one of the following must be provided:
- `collection_id` — run on all documents in a collection
- `document_id` — run on a single document in a collection
- `files` — one or more files uploaded directly in the request body (multipart/form-data) without adding them to a collection

This endpoint blocks and waits for the extraction to complete, then returns the results.

This endpoint is primarily intended for short-running extractions where immediate
results are desired.

For very long running extractions use the async endpoint
`/extractors/{extractor_id}/job` instead.

## Path parameters

- `extractor_id` string, required

## Query parameters

- `collection_id` string
- `document_id` string
- `timeout` number, double

## Request body `multipart/form-data`

- object
  - `files` string[]: One or more files to run the extractor on directly, without adding them to a collection. Mutually exclusive with collection_id and document_id.

## Response `200`

Extraction completed successfully. Returns an array of extraction results,
one for each document processed.

- DocumentExtractionResult[]
  - `id` string, required: ID of the document extraction result
  - `document_id` string, nullable: ID of the document that was processed. Null when the extraction was run on uploaded files without a collection.
  - `document_name` string, required: Name of the document that was processed
  - `content` unknown, required
  - `error` string, required: Contains error in case extraction failed for this document. Otherwise empty.

## Other responses

- `400`: Bad request
- `401`: Unauthorized - Invalid or missing API key
- `404`: Not found
- `default`: Unexpected error

---

[API](https://skmtc.dev/h2o/apis/h2ogpte-rest-api.md) - [All operations](https://skmtc.dev/h2o/apis/h2ogpte-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/h2o/apis/h2ogpte-rest-api/revisions/a82a117320f4?raw)