Skip to main content

Creating a Job

A Job is the quick path: a one-time run where a schema meets documents and AI extraction produces structured data in a single ad-hoc run. A job produces a grid: rows = documents, columns = schema fields. Each cell contains an extracted value along with metadata including a confidence score, the resolution type, the Job phase that produced it, and an AI reasoning trace explaining how the value was derived from the source document. Use a Job when you want results now and the work does not justify configuring a Spec.

Jobs and Pipelines are two paths to the same outcome. A Job is the fast path: pick a schema and documents and run. A Spec run (a Pipeline on the engine) is the production path: a reusable rail with Data Policies, validation checkpoints, a review queue, and assembly. Reach for a Job for ad-hoc work, and graduate to a Spec when the same document kind recurs. See The Spec & the Engine for the production path.

Open the Extract slide-over with Cmd+J or from an in-page entry point, or call POST /v1/jobs. Select your template and documents, then click Start. Results appear progressively as each phase completes. The platform supports three extraction modes: pipeline (the mode name for full 4-phase Job extraction, the default), simple (a single AI call, faster but less thorough), and field registry (no AI, deterministic strategies only; an admin-only mode for benchmarking registry coverage).

When you start a job, the platform runs a pre-flight check to ensure all selected documents have completed their field resolution step. If any document was uploaded recently and has not yet been resolved against the Field Registry, the system automatically resolves it before entering Phase 1. This lazy resolution gate prevents silent data loss where registry-based lookups would return empty results for unresolved documents. The pre-flight resolution runs with a concurrency of 3 and failures are non-fatal — Phase 1 will proceed with whatever is resolved.

For best results, select documents of the same type or closely related types for a single job. The schema you choose should match the document content — using an invoice schema on contract documents will produce poor results. Start with a small batch of 5-10 documents to validate your schema, review the output, apply corrections, and then scale up to larger runs once you are confident in the extraction quality.

The platform supports scaling caps to ensure reliable processing: Phase 2 extraction handles up to 2,000 documents per job, and Phase 4 transforms support up to 1,000 documents. Grid results are flushed to the database in batches of 200 documents per phase. For very large document collections, consider splitting into multiple jobs by document type for optimal results and easier review.

Create a Job via API
curl -X POST https://api.talonic.com/v1/jobs \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "document_ids": ["f0e1d2c3-b4a5-9687-8765-432109876543"],
    "name": "Q1 Invoice Processing"
  }'

# Response (201):
# {
#   "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
#   "status": "pending",
#   "message": "Job created and queued for processing.",
#   "links": {
#     "self": "/v1/jobs/c3d4e5f6-a7b8-9012-cdef-123456789012",
#     "results": "/v1/jobs/c3d4e5f6-a7b8-9012-cdef-123456789012/results"
#   }
# }

# document_ids is optional: omit it (or pass an empty array) to run
# the job against every completed document in your workspace.
Check job status
curl -s https://api.talonic.com/v1/jobs/c3d4e5f6-a7b8-9012-cdef-123456789012 \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Response:
# {
#   "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
#   "name": "Q1 Invoice Processing",
#   "status": "processing",
#   "progress": 45,
#   "current_phase": "phase_2_execute",
#   "document_count": 150,
#   "completed_documents": 67,
#   "grid_stats": {
#     "total_cells": 8850,
#     "filled": 6200,
#     "empty": 2650,
#     "fill_rate": 0.70
#   }
# }

The strategy yield breakdown on the job detail page is a powerful diagnostic tool. It shows exactly how each cell was filled — registry transfers from Phase 1, LLM extractions from Phase 2, lookup cascade matches from Phase 3, and deterministic computations. A high registry_transfer percentage indicates mature field coverage, while a high llm_extract percentage suggests the registry needs more training data. Track strategy yield across jobs to measure how your extraction efficiency improves over time as the Field Registry grows.

Results appear progressively as each Job phase completes. You do not need to wait for the entire job to finish — you can begin reviewing Phase 1 results while Phase 2 is still running. The phase timeline on the job detail page shows which phase is active and the cumulative fill rate at each stage.

Frequently asked questions

How do I create a Job?+
Open the Extract slide-over with Cmd+J or from an in-page entry point, or call POST /v1/jobs. Select your template and documents, then click Start. Results appear progressively as each Job phase completes.
What does a Job produce?+
A job produces a structured grid where rows represent documents and columns represent schema fields. Each cell contains an extracted value with confidence and provenance metadata.
How many documents can I include in a single job?+
Phase 2 supports up to 2,000 documents per job, and Phase 4 supports up to 1,000. For best results, start with smaller batches to validate your schema before scaling up.
What extraction modes are available?+
Three modes: pipeline (full 4-phase extraction, the default and most thorough), simple (a single AI call, faster but less thorough, used for test extractions), and field registry (no AI, deterministic strategies only; an admin-only mode for benchmarking how much the registry can resolve without AI). Choose pipeline for real workloads and simple for quick previews.
Do I have to select documents when creating a job via the API?+
No. The document_ids field on POST /v1/jobs is optional. If you omit it or pass an empty array, the job runs against every completed document in your workspace. Pass explicit document IDs when you want to scope the run to a specific set, which is recommended while validating a new schema.

Related

The Four Job Phases
User Templates
Reviewing Results
The Spec & the Engine (production path)