Skip to main content

​
What it does

The extract model, called through the OpenAI-compatible POST /v1/chat/completions endpoint, runs Named Entity Recognition (NER) over arbitrary text - but instead of a fixed set of entity types (person, place, organization), you define exactly what you’re looking for in plain English. The model interprets your descriptions and finds matching spans in the text, returning each one with a confidence score, character offsets, and surrounding context. This makes it practical to extract domain-specific entities that generic NER models don’t support: contract parties, product SKUs, medical terms, financial figures, custom identifiers, or anything else you can describe.

​
When to use it

You need structured data from unstructured text. If your pipeline involves parsing documents, emails, web pages, or transcripts to pull out specific values, Extract replaces brittle regex patterns and rigid NLP pipelines with a flexible, description-driven approach. Your entity types don’t fit standard NER. Off-the-shelf NER handles names, locations, and organizations. Extract handles whatever you define - lease terms, part numbers, clinical findings, competitor mentions, or any other domain-specific concept. You need confidence scores. Extract returns a confidence score for every result. Set a threshold (globally or per entity type) to drop low-confidence hits, or use the scores to route extractions to a human review queue. You want context alongside every result. Every extracted span comes with 500 characters of surrounding text on each side, so you can verify the extraction in context without going back to the source document. Your source is an image or scan, not text. Send a base64-encoded photo, scan, or PDF in the document field (via extra_body) and Extract reads the text before extraction - so receipts, invoices, IDs, business cards, and scanned forms work without a separate preprocessing step. See Extracting from an image or PDF. Some of your fields are decisions, not spans. Booleans and small categories - “is this account past due?”, “electric or gas?” - have no verbatim span to pull. Constrain those keys to a fixed set of choices (an enum, or a oneOf of const branches) and Extract routes them to the classification model, which is a Constrained Decoding Model (CDM) purpose-built for categorical decisions, while extracting the rest as normal. Per-label rubrics (via oneOf) describe when each label applies and meaningfully improve accuracy. See Classification keys.

​
Common use cases

​
How it fits into your workflow

Extract sits between your document ingestion step and whatever system consumes structured data - a database, a downstream process, or a human review interface.
Each entity in the response includes character offsets (start, end), so you can highlight or link back to the exact location in the source document.

​
Tips for better results

The entity name and description are treated as part of the model’s prompt - how you phrase them directly affects extraction quality.
  • Use lowercase or Title Case labels. The model was trained with lowercase entity names. person, company, and date work better than PERSON or DATE.
  • Be specific, and test synonyms. person and full name find slightly different things. If results are missing or noisy, try rephrasing the label name.
  • Labels can be descriptive phrases. "capital city and population center" is a perfectly valid label name and will outperform a bare "city" when you need that distinction.
  • Descriptions can be instructions. Write "Find the first and last name of the person in the text" rather than just "Name". Full instructions consistently outperform short noun phrases.
  • Don’t mix overlapping granularities. Including both "location" and "city" in the same call forces the model to split results between them unpredictably. Pick one level of granularity per concept.

​
Compared to traditional NER