Processing History

Processing history records represent individual document OCR jobs — each upload creates one record that tracks status, the extracted result, timing, and any errors. Use these endpoints to poll for completion, retrieve results, or export data in your preferred format.

Project ID requirement: For organization tokens, all endpoints require a projectId query parameter. For project tokens, projectId is inferred from the token automatically and is optional.

List Processing History

GET /v1/openapi/processing-history

Returns a paginated list of processing history records for the specified project. Supports filtering by status, template, date range, and search term.

Headers:

Header	Value	Required
`X-API-Key`	`ocr_your_api_key`	Yes

Query Parameters:

Parameter	Type	Required	Description
`projectId`	string	Org token: Yes	Target project ID
`page`	number	No	Page number (default: `1`)
`limit`	number	No	Items per page (default: `10`)
`status`	string	No	Filter by status: `pending`, `queued`, `in_progress`, `completed`, `failed`
`templateId`	string	No	Filter by template ID
`fromDate`	string	No	Start of date range (`YYYY-MM-DD`)
`toDate`	string	No	End of date range (`YYYY-MM-DD`)
`search`	string	No	Search by file name or template name
`batchId`	string	No	Filter by batch ID

Example Request:

curl "https://api.ocriva.com/v1/openapi/processing-history?projectId=68db4aa2967d9c03fa9b5e74&status=completed&page=1&limit=10" \
  -H "X-API-Key: ocr_your_api_key"

Example Response (200 OK):

{
  "data": [
    {
      "id": "68dc1cc4b78f0d15ec2a7f91",
      "uploadId": "68dc1bb3a67e0c14eb1b6e80",
      "projectId": "68db4aa2967d9c03fa9b5e74",
      "userId": "68da3991c56e8b02ea1b4d60",
      "fileName": "invoice-2026.pdf",
      "fileUrl": "https://storage.ocriva.com/org-abc/invoice-2026.pdf",
      "filePath": "org-abc/projects/proj-xyz/invoice-2026.pdf",
      "fileSize": "204800",
      "mimeType": "application/pdf",
      "status": "completed",
      "templateId": "68db4bb3a67e9c04fb0c6f85",
      "templateName": "Invoice Template",
      "resultFormat": "json",
      "priority": "medium",
      "processingResult": {
        "invoiceNumber": "INV-2026-0042",
        "totalAmount": 1250.00,
        "vendor": "Acme Corp"
      },
      "startedAt": "2026-03-31T10:01:00.000Z",
      "completedAt": "2026-03-31T10:01:15.000Z",
      "createdAt": "2026-03-31T10:00:00.000Z",
      "updatedAt": "2026-03-31T10:01:15.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "pages": 5
  }
}

Get Processing Statistics

GET /v1/openapi/processing-history/stats

Returns aggregated counts of processing records grouped by status for the specified project. Useful for building dashboards or monitoring pipelines.

Headers:

Header	Value	Required
`X-API-Key`	`ocr_your_api_key`	Yes

Query Parameters:

Parameter	Type	Required	Description
`projectId`	string	Org token: Yes	Target project ID

Example Request:

curl "https://api.ocriva.com/v1/openapi/processing-history/stats?projectId=68db4aa2967d9c03fa9b5e74" \
  -H "X-API-Key: ocr_your_api_key"

Example Response (200 OK):

{
  "total": 150,
  "pending": 5,
  "processing": 3,
  "completed": 138,
  "failed": 4
}

Get Processing History Record

GET /v1/openapi/processing-history/:id

Returns a single processing history record by its ID, including the full extracted result and timing details.

Path Parameters:

Parameter	Description
`id`	Processing history record ID

Headers:

Header	Value	Required
`X-API-Key`	`ocr_your_api_key`	Yes

Query Parameters:

Parameter	Type	Required	Description
`projectId`	string	Org token: Yes	Target project ID

Example Request:

curl "https://api.ocriva.com/v1/openapi/processing-history/68dc1cc4b78f0d15ec2a7f91?projectId=68db4aa2967d9c03fa9b5e74" \
  -H "X-API-Key: ocr_your_api_key"

Example Response (200 OK):

{
  "id": "68dc1cc4b78f0d15ec2a7f91",
  "uploadId": "68dc1bb3a67e0c14eb1b6e80",
  "projectId": "68db4aa2967d9c03fa9b5e74",
  "userId": "68da3991c56e8b02ea1b4d60",
  "fileName": "invoice-2026.pdf",
  "fileUrl": "https://storage.ocriva.com/org-abc/invoice-2026.pdf",
  "filePath": "org-abc/projects/proj-xyz/invoice-2026.pdf",
  "fileSize": "204800",
  "mimeType": "application/pdf",
  "status": "completed",
  "templateId": "68db4bb3a67e9c04fb0c6f85",
  "templateName": "Invoice Template",
  "resultFormat": "json",
  "priority": "medium",
  "processingResult": {
    "invoiceNumber": "INV-2026-0042",
    "totalAmount": 1250.00,
    "vendor": "Acme Corp",
    "lineItems": [
      { "description": "Consulting Services", "quantity": 1, "unitPrice": 1250.00 }
    ]
  },
  "startedAt": "2026-03-31T10:01:00.000Z",
  "completedAt": "2026-03-31T10:01:15.000Z",
  "createdAt": "2026-03-31T10:00:00.000Z",
  "updatedAt": "2026-03-31T10:01:15.000Z"
}

Common Errors:

Status	Cause
`401`	Record does not belong to the token's scope
`404`	Record not found

Export Processing Result

GET /v1/openapi/processing-history/:id/result

Downloads the processing result as a file in the specified format. The response streams the file directly with appropriate Content-Type and Content-Disposition headers set for download.

If no format is specified, the format defaults to the template's configured resultFormat, or json if no template is set.

Path Parameters:

Parameter	Description
`id`	Processing history record ID

Headers:

Header	Value	Required
`X-API-Key`	`ocr_your_api_key`	Yes

Query Parameters:

Parameter	Type	Required	Description
`projectId`	string	Org token: Yes	Target project ID
`format`	string	No	Output format: `json`, `text`, `xml`, `html`, `csv`, `pdf`, `docx`

Example Request:

# Download result as CSV
curl "https://api.ocriva.com/v1/openapi/processing-history/68dc1cc4b78f0d15ec2a7f91/result?projectId=68db4aa2967d9c03fa9b5e74&format=csv" \
  -H "X-API-Key: ocr_your_api_key" \
  -o "invoice-result.csv"

The response is a file download. For json format the body is a JSON object; for other formats, binary or text content is returned with the appropriate MIME type.

Supported Formats:

Format	Content-Type
`json`	`application/json`
`text`	`text/plain`
`xml`	`application/xml`
`html`	`text/html`
`csv`	`text/csv`
`pdf`	`application/pdf`
`docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`

Common Errors:

Status	Cause
`401`	Record does not belong to the token's scope
`404`	Record not found

Documents

Processing History

Processing History

List Processing History

Get Processing Statistics

Get Processing History Record

Export Processing Result

Table of Contents