{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-index.sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Extract","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"span","attributes":{"style":{"color":"#cdcefb","fontSize":"14px","fontWeight":"700","textTransform":"uppercase","letterSpacing":"0.05em","display":"block","marginBottom":"-30px"}},"children":["Get Started"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"extract","__idx":0},"children":["Extract"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pull structured JSON from documents using one existing schema."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Extract is the Anesya endpoint for turning a document or a completed parsing into structured data."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You provide:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["one schema ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["and either one document input or one parsing ID"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Anesya then returns a structured JSON result in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}," field."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Under the hood, extract relies on parsing. If you pass a raw document, a parsing is created first. If you pass a parsing ID, that parsing must already be complete enough to be reused."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"parsing-vs-extract","__idx":1},"children":["Parsing vs extract"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both endpoints process documents, but they solve different problems."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"parsing-answers","__idx":2},"children":["Parsing answers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["\"What is in this document?\""]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use parsing when you need:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["OCR output"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["markdown content"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["pictures"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["page-level success and failure details"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["direct inspection of the source content"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"extract-answers","__idx":3},"children":["Extract answers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["\"What structured result should I return from this document?\""]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use extract when you need:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["structured JSON"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["one schema-driven result"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a clean downstream payload for your app, workflow, or automation"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"important-rule","__idx":4},"children":["Important rule"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Extract can only work from what parsing can process."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the parsing is poor, incomplete, or fails, the extract result will be affected too."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When debugging extraction quality, inspect the parsing first."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-extract-is-for","__idx":5},"children":["What extract is for"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Extract is the right entry point when you want to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["map a document to one business schema"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["return a compact JSON payload instead of full document content"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["process one already parsed document"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["process one stored document, one URL, or one uploaded file in a single call"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The common flow is:"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart LR\n A[Document or parsing] --> B[Create extract]\n B --> C[Poll extract]\n C --> D[Use structured JSON]\n","diagramHtml":"","diagramHtmlDark":""},"children":["flowchart LR\n A[Document or parsing] --> B[Create extract]\n B --> C[Poll extract]\n C --> D[Use structured JSON]\n"]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"quick-start","__idx":6},"children":["Quick start"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The fastest extract workflow has two variants."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"option-a-extract-from-an-existing-parsing","__idx":7},"children":["Option A: Extract from an existing parsing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is the safest option when you already created a parsing or want maximum visibility."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.anesya.app/v0/extract\" \\\n -H \"X-API-Key: $ANESYA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"parsing\": \"YOUR_PARSING_ID\",\n \"schema\": \"YOUR_SCHEMA_ID\"\n }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this path when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the parsing already exists"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["you want to inspect parsing output before extraction"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["you want to reuse one parsing in downstream logic"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"option-b-extract-directly-from-one-document","__idx":8},"children":["Option B: Extract directly from one document"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is the simplest one-call path when you only need one final structured result."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.anesya.app/v0/extract\" \\\n -H \"X-API-Key: $ANESYA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"document\": \"YOUR_DOCUMENT_ID\",\n \"schema\": \"YOUR_SCHEMA_ID\",\n \"model\": \"PIGALLE\",\n \"picture_description_enabled\": false,\n \"table_verification_enabled\": false\n }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document"]}," is used, Anesya creates a new parsing first and then runs the extract."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"poll-the-extract","__idx":9},"children":["Poll the extract"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.anesya.app/v0/extract/YOUR_EXTRACT_ID\" \\\n -H \"X-API-Key: $ANESYA_API_KEY\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Stop polling when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," is one of:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FINISHED"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ERROR"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For complete polling guidance, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials/quickstart"},"children":["API quickstart"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-you-get-back","__idx":10},"children":["What you get back"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The extract retrieve endpoint returns a resource shaped like this:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"e90f337f-4d7c-46d1-a2a7-13cf5d9d7cfe\",\n \"schema\": {\n \"id\": \"YOUR_SCHEMA_ID\",\n \"name\": \"Invoice schema\",\n \"description\": \"Schema used for extracting data from invoices.\",\n \"completion_mode\": \"CLASSIC\"\n },\n \"parsing\": {\n \"id\": \"d1b96998-f20e-4b6f-8fa5-78a70b1db9b2\"\n },\n \"result\": {\n \"invoice_number\": \"INV-2025-0042\",\n \"invoice_date\": \"2025-06-01\",\n \"total_amount\": 1280.5\n },\n \"status\": \"FINISHED\",\n \"error\": null,\n \"created_at\": \"2025-06-12T14:58:00.000000Z\",\n \"updated_at\": \"2025-06-12T14:58:20.000000Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"key-fields","__idx":11},"children":["Key fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it contains"},"children":["What it contains"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Metadata about the schema used for extraction"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parsing"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Related parsing resource"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Final structured JSON payload"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Current extract state"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Error message when extraction fails"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"input-options","__idx":12},"children":["Input options"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Extract accepts exactly one of:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parsing"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It always requires:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-existing-parsing-id","__idx":13},"children":["1. Existing parsing ID"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Best when parsing already exists and should be reused."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"parsing\": \"YOUR_PARSING_ID\",\n \"schema\": \"YOUR_SCHEMA_ID\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-existing-document-id","__idx":14},"children":["2. Existing document ID"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Best when the file is stored in Anesya and you want a one-call extract flow."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"document\": \"YOUR_DOCUMENT_ID\",\n \"schema\": \"YOUR_SCHEMA_ID\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-public-or-pre-signed-url","__idx":15},"children":["3. Public or pre-signed URL"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Best when the source file is hosted elsewhere."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"document\": \"https://example.com/invoice.pdf\",\n \"schema\": \"YOUR_SCHEMA_ID\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4-multipart-uploaded-file","__idx":16},"children":["4. Multipart uploaded file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Best when your app already has the local file content."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"multipart/form-data\ndocument=@invoice.pdf\nschema=YOUR_SCHEMA_ID\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Important behavior:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["extract documents one document at a time"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the public schema does ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," document a URL-list input for extract"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["if you need fan-out over multiple files, create multiple parsings first"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"request-rules","__idx":17},"children":["Request rules"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These rules are critical."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"rule-1-schema-is-always-required","__idx":18},"children":["Rule 1: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}," is always required"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every extract request must include one schema ID."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"rule-2-exactly-one-of-document-or-parsing","__idx":19},"children":["Rule 2: exactly one of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parsing"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not send both in the same payload."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"rule-3-parsing-must-already-be-usable","__idx":20},"children":["Rule 3: parsing must already be usable"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you send a parsing ID, that parsing must already be in:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FINISHED"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PARTIAL_FINISHED"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the parsing is still running, keep polling it first."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"rule-4-document-specific-parsing-options-only-apply-with-document","__idx":21},"children":["Rule 4: document-specific parsing options only apply with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These fields affect the internal parsing step only when you use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["model"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["picture_description_enabled"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["table_verification_enabled"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parsing"]},", those fields are not the main lever anymore because parsing already happened."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response-format-details","__idx":22},"children":["Response format details"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Extract has two main response moments."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"post-v0extract","__idx":23},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v0/extract"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create extract returns one extract object in a non-final state such as:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN_QUEUE"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN_PROGRESS"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["At that moment:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}," may be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the resource exists"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["processing is still ongoing"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"get-v0extractid","__idx":24},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v0/extract/{id}"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve extract returns the full extract resource with:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parsing"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"important-result-shape-rule","__idx":25},"children":["Important result-shape rule"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The public schema models ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}," as a generic JSON payload."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["That means ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}," can be:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["an object"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["an array of objects"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not hardcode extract handling as “always one flat object”."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The exact shape depends on the schema and the extraction outcome."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"extract-statuses","__idx":26},"children":["Extract statuses"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These are the possible extract states:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What to do"},"children":["What to do"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN_QUEUE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Accepted and waiting to start"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["keep polling"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN_PROGRESS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Extraction is running"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["keep polling"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FINISHED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Extraction completed successfully"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Extraction failed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Unlike parsing, extract does not expose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PARTIAL_FINISHED"]}," in the public schema."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":27},"children":["Best practices"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-prefer-extract-from-parsing-when-debugging-matters","__idx":28},"children":["1. Prefer extract-from-parsing when debugging matters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If quality matters and you want visibility, do not jump directly from raw document to extract."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["parsing"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["parsing review"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["extract from parsing"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This makes debugging much easier."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-prefer-direct-extract-when-you-only-need-the-final-result","__idx":29},"children":["2. Prefer direct extract when you only need the final result"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you do not need OCR or markdown separately, direct extract from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document"]}," is cleaner and shorter."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-keep-one-schema-per-business-outcome","__idx":30},"children":["3. Keep one schema per business outcome"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Extract behaves best when one schema corresponds to one clear business result."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Examples:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["invoice extraction schema"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["payslip extraction schema"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["contract summary schema"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Avoid overloading one schema with too many unrelated goals."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4-make-sure-the-parsing-is-ready-before-extract-from-parsing","__idx":31},"children":["4. Make sure the parsing is ready before extract-from-parsing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you send a parsing ID too early, extract will fail or behave unexpectedly."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always wait until parsing is in a usable final state."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"5-use-parsing-first-for-multiple-urls","__idx":32},"children":["5. Use parsing-first for multiple URLs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your input source is a list of URLs:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["send the list to parsing"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["receive multiple parsing IDs"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["create one extract per parsing"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"6-treat-result-as-arbitrary-json","__idx":33},"children":["6. Treat ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}," as arbitrary JSON"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not assume:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["one flat object"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["fixed field ordering"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a single fixed value type"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Consume ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}," based on the schema you asked for."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-pitfalls","__idx":34},"children":["Common pitfalls"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sending-both-document-and-parsing","__idx":35},"children":["Sending both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parsing"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is invalid. Extract expects exactly one source strategy."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"forgetting-schema","__idx":36},"children":["Forgetting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Without a schema ID, the request is incomplete."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sending-a-parsing-that-is-still-running","__idx":37},"children":["Sending a parsing that is still running"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If parsing has not reached ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FINISHED"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PARTIAL_FINISHED"]},", do not create the extract yet."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"assuming-extract-supports-a-list-of-urls","__idx":38},"children":["Assuming extract supports a list of URLs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["That behavior is documented on parsing, not on extract."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"assuming-result-is-ready-immediately-after-post","__idx":39},"children":["Assuming ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}," is ready immediately after ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Extract is asynchronous. Poll the resource before using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"treating-every-extract-result-as-the-same-json-shape","__idx":40},"children":["Treating every extract result as the same JSON shape"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The schema drives the result shape, so different schemas can produce very different payloads."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting","__idx":41},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"401-unauthorized","__idx":42},"children":["401 Unauthorized"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your API key is missing or invalid. Check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-API-Key"]}," header."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"extract-stays-in-in_queue-or-in_progress","__idx":43},"children":["Extract stays in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN_QUEUE"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN_PROGRESS"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep polling. Extract is asynchronous by design."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"extract-finishes-with-error","__idx":44},"children":["Extract finishes with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ERROR"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Inspect the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," field, then verify:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the schema ID is valid"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the parsing is already usable if you passed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parsing"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the document input is valid if you passed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["document"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"direct-extract-from-url-fails","__idx":45},"children":["Direct extract from URL fails"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the input uses a short-lived pre-signed URL, it may expire before the internal parsing step starts or finishes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use a longer validity window or upload the file first."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"output-quality-is-poor","__idx":46},"children":["Output quality is poor"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the extract result is weak or incomplete:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["inspect the parsing first"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["verify the document content appears correctly in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["markdown_content"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ocr_content"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["then review the schema you are using"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-guides","__idx":47},"children":["Related guides"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials/quickstart"},"children":["API quickstart"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials/parsing"},"children":["Parsing"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials/extract"},"children":["Extract guide"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials/quickstart"},"children":["Quickstart polling flow"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials/schemas/create_schema"},"children":["How to Build a JSON Extraction Schema"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/tutorials/agent-guide"},"children":["Anesya API Reference for Coding Agents"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api/schema/extracts/extract_create"},"children":["API reference"]}]}]}]},"headings":[{"value":"Extract","id":"extract","depth":1},{"value":"Parsing vs extract","id":"parsing-vs-extract","depth":2},{"value":"Parsing answers","id":"parsing-answers","depth":3},{"value":"Extract answers","id":"extract-answers","depth":3},{"value":"Important rule","id":"important-rule","depth":3},{"value":"What extract is for","id":"what-extract-is-for","depth":2},{"value":"Quick start","id":"quick-start","depth":2},{"value":"Option A: Extract from an existing parsing","id":"option-a-extract-from-an-existing-parsing","depth":3},{"value":"Option B: Extract directly from one document","id":"option-b-extract-directly-from-one-document","depth":3},{"value":"Poll the extract","id":"poll-the-extract","depth":3},{"value":"What you get back","id":"what-you-get-back","depth":2},{"value":"Key fields","id":"key-fields","depth":3},{"value":"Input options","id":"input-options","depth":2},{"value":"1. Existing parsing ID","id":"1-existing-parsing-id","depth":3},{"value":"2. Existing document ID","id":"2-existing-document-id","depth":3},{"value":"3. Public or pre-signed URL","id":"3-public-or-pre-signed-url","depth":3},{"value":"4. Multipart uploaded file","id":"4-multipart-uploaded-file","depth":3},{"value":"Request rules","id":"request-rules","depth":2},{"value":"Rule 1: schema is always required","id":"rule-1-schema-is-always-required","depth":3},{"value":"Rule 2: exactly one of document or parsing","id":"rule-2-exactly-one-of-document-or-parsing","depth":3},{"value":"Rule 3: parsing must already be usable","id":"rule-3-parsing-must-already-be-usable","depth":3},{"value":"Rule 4: document-specific parsing options only apply with document","id":"rule-4-document-specific-parsing-options-only-apply-with-document","depth":3},{"value":"Response format details","id":"response-format-details","depth":2},{"value":"POST /v0/extract","id":"post-v0extract","depth":3},{"value":"GET /v0/extract/{id}","id":"get-v0extractid","depth":3},{"value":"Important result-shape rule","id":"important-result-shape-rule","depth":3},{"value":"Extract statuses","id":"extract-statuses","depth":2},{"value":"Best practices","id":"best-practices","depth":2},{"value":"1. Prefer extract-from-parsing when debugging matters","id":"1-prefer-extract-from-parsing-when-debugging-matters","depth":3},{"value":"2. Prefer direct extract when you only need the final result","id":"2-prefer-direct-extract-when-you-only-need-the-final-result","depth":3},{"value":"3. Keep one schema per business outcome","id":"3-keep-one-schema-per-business-outcome","depth":3},{"value":"4. Make sure the parsing is ready before extract-from-parsing","id":"4-make-sure-the-parsing-is-ready-before-extract-from-parsing","depth":3},{"value":"5. Use parsing-first for multiple URLs","id":"5-use-parsing-first-for-multiple-urls","depth":3},{"value":"6. Treat result as arbitrary JSON","id":"6-treat-result-as-arbitrary-json","depth":3},{"value":"Common pitfalls","id":"common-pitfalls","depth":2},{"value":"Sending both document and parsing","id":"sending-both-document-and-parsing","depth":3},{"value":"Forgetting schema","id":"forgetting-schema","depth":3},{"value":"Sending a parsing that is still running","id":"sending-a-parsing-that-is-still-running","depth":3},{"value":"Assuming extract supports a list of URLs","id":"assuming-extract-supports-a-list-of-urls","depth":3},{"value":"Assuming result is ready immediately after POST","id":"assuming-result-is-ready-immediately-after-post","depth":3},{"value":"Treating every extract result as the same JSON shape","id":"treating-every-extract-result-as-the-same-json-shape","depth":3},{"value":"Troubleshooting","id":"troubleshooting","depth":2},{"value":"401 Unauthorized","id":"401-unauthorized","depth":3},{"value":"Extract stays in IN_QUEUE or IN_PROGRESS","id":"extract-stays-in-in_queue-or-in_progress","depth":3},{"value":"Extract finishes with ERROR","id":"extract-finishes-with-error","depth":3},{"value":"Direct extract from URL fails","id":"direct-extract-from-url-fails","depth":3},{"value":"Output quality is poor","id":"output-quality-is-poor","depth":3},{"value":"Related guides","id":"related-guides","depth":2}],"frontmatter":{"seo":{"title":"Extract"}},"lastModified":"2026-04-22T15:07:29.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/tutorials/extract","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}