---
title: "Check parser availability and estimated usage"
method: POST
path: "/parser/preflight"
tags: ["Parsing API"]
---

# Check parser availability and estimated usage

`POST /parser/preflight`

## Request

- Base URL: `https://contracko.com/api/v1`
- URL: `https://contracko.com/api/v1/parser/preflight`
- Auth: one of:
  - API key in header `x-contracko-api-key`
  - HTTP bearer

Validate one or more files before upload and return the estimated usage for the batch.

## Request body

- object: Request body for estimating usage before you queue a batch.
  - `runKind` 'extraction' | 'review': Request type. extraction performs structured extraction only; review adds AI analysis and costs extra credits.
  - `outputLanguage` 'source' | 'en' | 'nl' | 'de' | 'fr' | 'es' | 'it' | 'pt' | 'zh-Hans' | 'zh-Hant' | 'ja' | 'ko' | 'ar' | 'hi' | 'bn' | 'ta' | 'te' | 'mr' | 'ur' | 'id' | 'vi' | 'th' | 'pl' | 'sv' | 'da' | 'no' | 'fi' | 'tr' | 'ru' | 'uk' | 'ro' | 'cs' | 'hu' | 'el': Optional AI output language. Omit to use the workspace default; use source to preserve the document language.
  - `outputTemplateId` 'standard': Export layout template. standard keeps the default Contracko parser columns.
  - `deidentification` object: Optional document-scoped protection policy. Omit for an unprotected result; pass an empty object for the contract-safe default.
    - `policyVersionId` 'contract-safe-v1'
    - `consistencyScope` 'document'
    - `overrides` object[]
      - `match` object, required
        - `entityType` 'person' | 'organisation' | 'email' | 'phone' | 'address' | 'identifier' | 'secret'
        - `fieldPath` string
      - `action` union, required
        - object
          - `type` 'keep', required
        - object
          - `type` 'replace', required
          - `strategy` 'linked'
        - object
          - `type` 'generalize', required
          - `precision` 'city-country', required
        - object
          - `type` 'remove', required
  - `files` object[], required: Files to validate for parser processing
    - `fileName` string, required: Original file name including extension
    - `mimeType` string, required: RFC MIME type of the source file
    - `fileSize` integer, required: File size in bytes
    - `pageCountEstimate` integer: Optional page count estimate to improve credit estimation

## Response `200`

Availability and estimated usage returned.

- object
  - `creditsNeeded` integer, required: Estimated credits required for this request
  - `totalBytes` integer, required: Total request payload size in bytes
  - `errors` string[], required: Validation messages returned during preflight
  - `fileCredits` object[], required: Per-file credit breakdown
    - `fileName` string, required: File name from the request
    - `credits` integer, required: Credits required for this file
    - `baseCredits` integer, required: Base extraction credits for this file
    - `analysisCredits` integer, required: Additional review credits for this file
    - `index` integer, required: Original file index in the request payload
  - `breakdown` object, required: Credit breakdown by requested parser capability
    - `extraction` integer, required: Credits for structured extraction
    - `analysis` integer, required: Additional credits for AI review analysis
    - `outputLanguage` integer, required: Additional credits for output-language conversion, currently included at no surcharge
    - `extractionTemplate` integer, required: Additional credits for extraction-template fields, currently included at no surcharge
  - `limits` object, required
    - `maxFileBytes` integer, required: Maximum file size accepted per file
    - `maxBatchBytes` integer, required: Maximum aggregate batch size
    - `maxBatchFiles` integer, required: Maximum number of files per batch
  - `balance` object, required
    - `allocated` integer, required: Allocated credits in the current billing cycle
    - `used` integer, required: Credits consumed in the current billing cycle
    - `remaining` integer, required: Credits available for new parser jobs
    - `sourcePlanKey` string, required: Plan identifier associated with this usage window
  - `concurrency` object, required
    - `active` integer, required: Parser batches currently in progress
    - `max` integer, required: Maximum concurrent parser batches allowed

## Other responses

- `400`: Request validation failed (payload, query, or path format is invalid).
- `401`: Authentication failed (missing, invalid, revoked, or expired API key).
- `403`: Access denied because this API key does not include parsing access or the Parsing API is not available for this workspace.
- `429`: Retry later because the request rate limit was reached or too many parser batches are already running for this workspace.
- `500`: The server could not complete the request.

---

[API](https://skmtc.dev/contracko/apis/contracko-parsing-api.md) · [All operations](https://skmtc.dev/contracko/apis/contracko-parsing-api/llms.txt) · [OpenAPI document](https://skmtc.dev/contracko/apis/contracko-parsing-api/revisions/2f90b1d3cafd?raw)