Jobs
How Parsings and Operations process a Document, and what they have in common.
A Job processes one Document. There are two families of Jobs:
- a Parsing turns the Document into a structured Parsed Document of pages and blocks, which you read as Markdown, text, HTML or JSON;
- an Operation runs a language model on the Document: Summarization, Classification or Extraction.
Each kind is a resource of its own, with the same endpoints:
| Kind | Resource | Output |
|---|---|---|
| Parsing | /parsings | The Parsed Document, at /{parsing_id}/output |
| Summarization | /summarizations | A title and a summary, in output |
| Classification | /classifications | A category and its motivation, in output |
| Extraction | /extractions | The fields of your JSON Schema, in output |
Every Operation parses its Document itself, with the parsing settings of its own configuration: it never reuses a Parsing you submitted. To summarize and classify the same Document, submit one Summarization and one Classification: each runs, fails and is billed on its own.
🏗️ Configuration
The configuration of a Job is sent as JSON in the config form field. Every Job has a perimeter; the other fields depend on its kind.
| Field | Jobs | Default | Description |
|---|---|---|---|
perimeter | all | external | Where your data may go, for the Parsing and the language model. See Perimeters. |
tier | Parsing | fast | The Parsing Tier: how the Document is read. See Parse. |
pages | Parsing | all pages | The pages to parse. See Parse. |
parsing | Operations | { "tier": "fast" } | How the Operation parses the Document: its Parsing Tier and pages, as for a Parsing. |
tier | Operations | fast | The Operation Tier: the language model. See Operation Tiers. |
instructions | Operations | none | Extra instructions for the model. |
Each Operation adds its own fields: see Summarize, Classify and Extract.
🔄 Lifecycle
A Job is queued, then running, then done or failed. A failed Job produced nothing and costs nothing.
The wait query parameter (up to 30 seconds) keeps the request open until the Job finishes: the response is 200 when it finished, 202 while it is still running. Read the Job again, with wait, until it finishes. For example, with a Summarization:
A done Operation carries its Output in output: value holds what the model returned, truncated: true says the Document was longer than the Operation can read, and the model read only its start.
💳 Credits
| Job | Credits |
|---|---|
| Parsing | accurate Parsing of PDFs, images and presentations: one per page. Any other Parsing: one. |
| Operation | Its Parsing, as above, plus one for a fast Operation or three for an accurate one (Operation Tiers). |
A Job is charged once it is done, and its cost is in its credits. When the workspace has no Credits left, new Jobs are rejected with 402 balance_exhausted.
🛠️ Submit a Job
Every kind is submitted the same way. Pass exactly one of file (uploaded as a new Document) or documentId (a Document you already uploaded).
curl -X POST "https://api.axelered.com/v1/summarizations?wait=30" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "documentId={document_id}" \
-F 'config={"length": "short", "parsing": {"tier": "accurate"}}'Add idempotency_key=<key> to the query to make a retry safe: a key already used in the workspace for the same kind returns 409 idempotency_conflict.
| Error | When |
|---|---|
400 unreadable_file | The file is corrupt and its pages cannot be read. |
400 unsupported_format | The file type is not supported, or not with accurate Parsing. |
402 balance_exhausted | The workspace has no Credits left. |
403 perimeter_not_allowed | The workspace only allows local. See Compliance Guard. |
404 | The documentId does not exist. |
409 idempotency_conflict | The idempotency key was already used; the Location header is the Job that holds it. |
413 too_many_pages | accurate Parsing would read more than 100 pages. See Documents. |
422 invalid_output_schema | The outputSchema of an Extraction is not a valid JSON Schema. |
503 perimeter_unavailable | The Perimeter cannot run this Job. See Perimeters. |
All the codes and the error format are in Errors.
List, Read & Delete
Each resource has the same three endpoints, documented in the API reference of its kind:
- List: newest first, optionally for one Document with
?documentId=. Lists leave out theoutputof Operations. - Read: status, credits and, for a done Operation, its
output, with optionalwait. - Delete: hide a Job. Its Document is kept.
Deleting a Document hides all its Jobs, and their files are removed with it.