--- name: "files_ocr" area: "files" title: "Read a scan with OCR" price: "$0.005 per page read" method: "POST" url: "https://api.conecto.chat/v1/tools/files_ocr" mcp_server: "https://api.conecto.chat/mcp/files" auth: "Authorization: Bearer " docs_url: "https://conecto.chat/tools/files/files_ocr" --- # Read a scan with OCR (`files_ocr`) Reads the words in a scan with OCR: an image, or the pages of a PDF without text; the text is kept. Read the words in a scan with OCR (Tesseract): an image (PNG, JPEG, TIFF, WebP) or the pages of a PDF that have no text of their own, up to 100 pages (pages with text keep it). The text is kept: files_read_text and account_search find it afterwards, free. languages: up to 3 (default: the account's, see files_ocr_settings). max_pages is the most this call may read; it holds $0.005 for each until the reading is done, then charges the pages read. OCR reads what is printed; making sense of it is your work. Price: $0.005 per page read. A call that fails costs nothing. ## Use it when A scan or a photo of a document should become text that can be read and found. - For looking at the scan yourself, use [documents_page_images](https://conecto.chat/tools/documents/documents_page_images.md). ## Say this to your agent > Read the scanned delivery receipt so we can search it later. ## Inputs | Name | Type | Required | Description | Allowed values | Default | |---|---|---|---|---|---| | `file_id` | string | yes | The file_id files_upload returned. Exactly 36 characters. | | | | `languages` | array of strings | no | Up to 3 of eng, deu, fra, spa, ita, nld, por, swe. Up to 3 items. | `"eng"`, `"deu"`, `"fra"`, `"spa"`, `"ita"`, `"nld"`, `"por"`, `"swe"` | | | `max_pages` | integer | no | 1 to 100. | | `100` | ## Example Written for Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon. MCP: call `files_ocr` on the MCP server `https://api.conecto.chat/mcp/files` with these arguments: ```json { "file_id": "3a5c7e9b-1d4f-4a6c-8e0a-2c4e6a8c0b3e", "languages": [ "deu", "eng" ] } ``` REST: ```bash curl https://api.conecto.chat/v1/tools/files_ocr \ -H "Authorization: Bearer $CONECTO_KEY" \ -H "Content-Type: application/json" \ -d '{"file_id": "3a5c7e9b-1d4f-4a6c-8e0a-2c4e6a8c0b3e", "languages": ["deu", "eng"]}' ``` ## Response This tool runs in the background. The first reply has status `202`: ```json { "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93", "tool": "files_ocr", "status": "running", "reserved_usd": "$0.50", "poll": "GET /v1/calls/5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93 (or the account_get_call tool) until status is succeeded or failed. You are charged only when it succeeds." } ``` Poll `GET https://api.conecto.chat/v1/calls/` (or call `account_get_call`) until `status` is `succeeded` or `failed`. When it succeeds, `output` holds the result: ```json { "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93", "tool": "files_ocr", "area": "files", "status": "succeeded", "cost_usd": "$0.005", "error": null, "message": null, "latency_ms": 4210, "at": "2026-10-14T08:00:00+00:00", "bot": "Pip", "person": null, "input": { "file_id": "3a5c7e9b-1d4f-4a6c-8e0a-2c4e6a8c0b3e", "languages": [ "deu", "eng" ] }, "output": { "file_id": "3a5c7e9b-1d4f-4a6c-8e0a-2c4e6a8c0b3e", "pages_read": 1, "total_pages": 1, "languages": [ "deu", "eng" ], "length": 94, "text": "Packing slip PS-2026-1043\nCascade Bike Supply\n12 tires, 700x40\nReceived: Sam Reyes, 10/13/2026" } } ``` `output`: When it finishes: the file_id, pages_read and total_pages, the languages used, and the text (up to 20,000 characters; files_read_text has the rest). ## Errors | Code | Status | When | Fix | |---|---|---|---| | `not_found` | 404 | No file of the business has that file_id. | Find it with files_list. | | `invalid_input` | 400 | A language is not one OCR reads here, or there are more than 3. | Use up to 3 of eng, deu, fra, spa, ita, nld, por, swe. | | `unsupported_type` | 400 | The file is not an image (PNG, JPEG, TIFF, WebP) or a PDF. | Read other files with files_read_text. | | `not_image` | 400 | The file says it is an image but cannot be read as one. | Upload it again as PNG or JPEG. | | `already_read` | 409 | The scan was read with OCR already. | Read its text free with files_read_text. | | `nothing_to_read` | 409 | Every page has text of its own. | Read it free with files_read_text. | | `in_progress` | 409 | This scan is being read right now. | Read it with files_read_text in a minute. | | `ocr_in_progress` | 409 | Another scan of the business is being read; OCR reads one at a time. | Call again once that call is done (account_get_call shows it). | | `too_many_pages` | 413 | The scan has more pages to read than max_pages. | Pass the max_pages the message names. | | `too_large` | 413 | The image is over 40 megapixels. | Shrink it with image_transform first. | | `pdf_locked` | 422 | The PDF is password-protected. | Ask for a copy without a password. | | `invalid_pdf` | 422 | The file is not a PDF that can be read. | Ask for another copy. | | `ocr_failed` | 422 | OCR could not read the file. | Try a sharper scan. | | `timeout` | 422 | Reading the scan took too long. | Read fewer pages at a time with max_pages. | | `crashed` | 422 | Reading the scan needed more memory or time than a file may use. | Split the scan, or send smaller pages. | | `busy` | 503 | Files are being read for other calls right now. | Try again in a minute; nothing was charged. | | `unavailable` | 503 | OCR is not switched on here yet. | Nothing was charged; try again later. | The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md ## Related - [files_upload](https://conecto.chat/tools/files/files_upload.md): Stores a file in the business's file store from its bytes, its text or a public link, with a download link. $0.001 a call. - [files_upload_link](https://conecto.chat/tools/files/files_upload_link.md): A one-time link to upload one file of up to 25 MB, to use yourself or hand to a person. Free. - [files_list](https://conecto.chat/tools/files/files_list.md): The business's files, newest first, filtered by name, words inside, tags, type, correspondent, document date or fields. Free up to 1,000,000 reads a month. - [files_get](https://conecto.chat/tools/files/files_get.md): One file's details and a fresh download link, with the text of a small text file if asked. Free up to 1,000,000 reads a month. - [files_read_text](https://conecto.chat/tools/files/files_read_text.md): The words in a file as Conecto read them: text files, PDFs, office files, HTML, and scans once read with OCR. Free up to 1,000,000 reads a month. - [files_edit](https://conecto.chat/tools/files/files_edit.md): Says what one file is, or up to 100 at once: title, notes, document date, correspondent, type, tags and fields. $0.005 per file changed. - [files_define](https://conecto.chat/tools/files/files_define.md): Adds, renames or deletes a tag, a document type, a custom field or a correspondent to file things with. $0.001 a call. - [files_definitions](https://conecto.chat/tools/files/files_definitions.md): The tags, document types, custom fields and correspondents the business files with, each with how many files use it, and the OCR settings. Free up to 1,000,000 reads a month. - [files_ocr_settings](https://conecto.chat/tools/files/files_ocr_settings.md): Sets whether new scans are read with OCR as they arrive, and the languages OCR reads in. $0.001 a call. - [files_delete](https://conecto.chat/tools/files/files_delete.md): Deletes a file for good; every download link to it stops working. Free. - [files_add_storage](https://conecto.chat/tools/files/files_add_storage.md): Rents 10 GB more file storage, renewed monthly from the balance; this call pays the first month. $1.00 a call. - [files_remove_storage](https://conecto.chat/tools/files/files_remove_storage.md): Stops renting one 10 GB block of storage, if the files still fit. Free.