Skip to navigation
ParseFiles

Parse Spreadsheet

Parse runs a file through the same parsing and chunking Captain uses for indexing and returns the chunks without storing them in a collection. The output is meant to be taken into another database or pipeline and managed there.

Accepts XLSX, XLSM, XLS, CSV and TSV files. Each chunk is a group of rows under its column headers, with the sheet name, row and column range, and row role on every chunk. Send the file as input: a direct download link, or the captain:// id from Upload File for a local file. Parsing runs as a job: this request returns 202 with a job_id, and the chunks come back from Get Parse Job once the job completes. Spreadsheets are billed at the indexing rates for spreadsheets: by the length of the sheet text, plus each image described when include_images is on. A failed or cancelled job is not billed.

Headers

authorizationstringOptional
Idempotency-KeystringOptional
Retrying a request with the same key returns the original job instead of starting a second one.

Request

This endpoint expects an object.
inputstringRequired

The file to parse, as one of:

  • A direct download link: a public HTTPS URL, or a presigned URL from S3, Google Cloud Storage, Azure Blob Storage or any other store.
  • A captain:// id returned by Upload File, for a file sent from local disk.

For a link, Captain copies the file into its own storage right after accepting the job, so the link only needs to work for a few seconds. A link that cannot be read, a file over 100 MB, or a file type the endpoint does not accept ends the job as failed with download_failed, file_too_large or unsupported_file_type, and nothing is billed.

include_tags_summarybooleanOptionalDefaults to false

When true, each chunk also carries the tags and summary Captain generates during indexing. These are model output, so two runs on the same file can return different values.

include_imagesbooleanOptionalDefaults to false

When true, images and charts in the workbook are described and returned as figure chunks.

include_verified_factsbooleanOptionalDefaults to false

When true, each row-group chunk carries verified_facts: exact per-column minimums, maximums and row counts computed from the rows in that chunk, with no model involved.

Response

Job accepted.
job_idstring
Identifier of the parse job.
typeenum
Allowed values:
statusenum
Allowed values:
status_urlstring
Path of the Get Parse Job endpoint for this job.
created_atstringformat: "date-time"

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
422
Unprocessable Entity Error
429
Too Many Requests Error
503
Service Unavailable Error