---
title: "Submit async batch job"
method: POST
path: "/api/batch"
---

# Submit async batch job

`POST /api/batch`

## Request

- Base URL: `https://financesec.api.caleralabs.com`
- URL: `https://financesec.api.caleralabs.com/api/batch`
- Auth: API key in header `X-License-Key`

Queue up to 100 queries for background processing. Available for Professional and Enterprise tiers only.

## Request body

- BatchRequest
  - `queries` string[], required

## Response `202`

Batch job queued successfully

- BatchJob
  - `batch_id` string
  - `status` 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED'
  - `total_queries` integer
  - `processed_queries` integer
  - `queries` string[]
  - `results` QueryResponse[]
    - `query_id` string
    - `status` 'VERIFIED_SUCCESS' | 'TENTATIVE_MATCH' | 'SAFE_REFUSAL' | 'EVENT_ACK_PENDING_FACTS' | 'EARNINGS_DAY_EMPTY' | 'OUT_OF_UNIVERSE' | 'SCHEDULE_NOT_IN_ONTOLOGY' | 'FILING_EVENT_SET': EVENT_ACK_PENDING_FACTS: 8-K Item 2.02 seen; certified metrics pending (see filing_event). EARNINGS_DAY_EMPTY / OUT_OF_UNIVERSE / SCHEDULE_NOT_IN_ONTOLOGY: typed honest silences (UX-SILENCE-TYPED-1). FILING_EVENT_SET: EDGAR-observed earnings-day set recall (Class B).
    - `source` 'LATTICE_RECALL' | 'ANALYTICAL_GATE' | 'TEMPORAL_GATE' | 'ENTITY_GATE' | 'CONFIDENCE_GATE' | 'FILING_EVENT_GATE' | 'CAPABILITY_GATE' | 'COVERAGE_GATE' | 'ONTOLOGY_GATE'
    - `coverage` object: Public coverage bound for earnings-day answers and typed silences. Never implies full-market calendar coverage.
      - `universe_description` string
      - `universe_size` integer
      - `model_generation` integer
      - `promoted_at` string, date-time
    - `answer` object
      - `value` number
      - `unit` string
      - `formatted` string
    - `filing_event` object: Structured 8-K event metadata (Item codes from SEC submissions). Present on EVENT_ACK_PENDING_FACTS. Never contains invented monetary values.
      - `form_type` string
      - `items` string[]
      - `event_type` string
      - `event_types` string[]
      - `cik` string
      - `ticker` string
      - `accession` string
      - `filing_date` string
      - `next_check` string
    - `confidence_score` number, float
    - `method` string
    - `provenance` object
      - `entity_id` string
      - `source_filing` string
      - `company` string
      - `xbrl_concept` string
      - `doc_period` string
      - `audit_hash` string
      - `original_value` string: Formatted reporting-currency value before FX conversion.
      - `original_unit` string: ISO reporting currency before FX conversion.
      - `fx_rate` string: Audited annual-average FX rate applied at inference time.
      - `fx_converted` boolean: True when the answer was converted from the filer's reporting currency.
    - `decomposition` object
      - `steps` object[]
        - `label` string
        - `value` string
      - `operator` string
      - `result` string
    - `reason` string: Human-readable refusal, typed silence, or pending-facts explanation. EVENT_ACK_PENDING_FACTS and UX-SILENCE-TYPED-1 classes use fixed product copy (not scraped from press HTML).
  - `created_at` string, date-time
  - `completed_at` string, date-time
  - `error` string

## Other responses

- `400`: Invalid batch payload or batch size exceeded
- `401`: Unauthorized
- `403`: Endpoint access forbidden for active tier

---

[API](https://skmtc.dev/caleralabs/apis/financesec-api-reference.md) · [All operations](https://skmtc.dev/caleralabs/apis/financesec-api-reference/llms.txt) · [OpenAPI document](https://skmtc.dev/caleralabs/apis/financesec-api-reference/revisions/fed76f2ec6e5?raw)