> ## Documentation Index > Fetch the complete documentation index at: https://developers.lighton.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get the status and result of an async parse job > Poll for the status and result of an async parse job submitted via `POST /api/v3/parse` with `options.async=true`. Returns the same envelope shape as the synchronous parse endpoint once `status` is `completed`. ```bash curl https://api.lighton.ai/api/v3/parse/parse_Kg \ -H 'Authorization: Bearer $TOKEN' ``` **Recommended polling cadence:** 1s for the first 10s, then 5s, capped at 30s. Stop polling once `status` is in `{completed, failed}`. ## OpenAPI ````yaml /api-reference/api-console.yaml get /api/v3/parse/{id} openapi: 3.1.0 info: title: LightOn API version: 3.12.0 (v1) description: >- LightOn gives you an API to search, parse, and ingest documents at scale. Build knowledge-retrieval pipelines without managing vector databases or OCR models. servers: - url: https://api.lighton.ai security: [] tags: - name: Ask description: >- Retrieval-augmented generation: search your indexed corpus and generate an LLM answer grounded in the retrieved passages. Supports streaming (SSE) and synchronous modes. - name: Search description: >- Hybrid vector + text retrieval over your indexed corpus. Returns ranked passages with provenance (file, page range, workspace). Optional reranking and vision mode. - name: Files description: Upload, list, fetch, and delete documents indexed in your workspaces. - name: Facets description: >- Organise documents with hierarchical content types and custom attributes per file. Start from starter templates or build your own classification schema from scratch. - name: Tags description: >- Manage flat, company-wide labels used to scope search and group content across workspaces. - name: Workspaces description: >- Create and manage workspaces — the access-controlled containers your documents live in. - name: Parse description: >- Convert documents into structured Markdown — PDFs, images, Office files, and HTML. Synchronous endpoint capped at 20 MB / 15 pages. - name: Extract description: >- Pull typed fields out of documents using a JSON Schema you provide. Sync mode for small documents (≤20 MB / 15 pages); async mode for larger jobs (≤100 MB / 1000 pages) with polling on a job ID. - name: API Keys description: >- Provision and revoke API keys used to authenticate against the Console API. - name: Budget description: >- Manage your organization's monthly spend budget and alert thresholds. Set a hard cap that blocks API requests when reached, and configure email notifications at custom spend percentages. paths: /api/v3/parse/{id}: get: tags: - Parse summary: Get the status and result of an async parse job description: >- Poll for the status and result of an async parse job submitted via `POST /api/v3/parse` with `options.async=true`. Returns the same envelope shape as the synchronous parse endpoint once `status` is `completed`. ```bash curl https://api.lighton.ai/api/v3/parse/parse_Kg \ -H 'Authorization: Bearer $TOKEN' ``` **Recommended polling cadence:** 1s for the first 10s, then 5s, capped at 30s. Stop polling once `status` is in `{completed, failed}`. operationId: api_v3_parse_retrieve parameters: - in: path name: id schema: type: string description: >- Public parse job id (e.g. `parse_Kg`) returned by `POST /api/v3/parse` with `options.async=true`. Malformed or unknown tokens return 404. required: true examples: AsyncJobId: value: parse_Kg summary: Async job id responses: '200': content: application/json: schema: $ref: '#/components/schemas/ParseJobStatus' examples: Pending—JustSubmitted: value: id: parse_Kg status: pending created_at: '2026-03-31T10:00:00+00:00' completed_at: null processing_time_ms: null document: filename: report.pdf page_count: null file_size_bytes: 245120 mime_type: application/pdf result: null usage: null progress: null error: null summary: Pending — just submitted description: >- Returned immediately after the 202; the job has not been picked up yet. Processing—InFlight: value: id: parse_Kg status: processing created_at: '2026-03-31T10:00:00+00:00' completed_at: null processing_time_ms: null document: filename: report.pdf page_count: null file_size_bytes: 245120 mime_type: application/pdf result: null usage: null progress: percentage: 27 pages_processed: 120 error: null summary: Processing — in flight description: >- A worker has picked up the job. `progress` reports pages parsed so far and the completion `percentage` [0, 100] so clients can show a determinate progress bar. Keep polling. Completed—TerminalSuccess: value: id: parse_Kg status: completed created_at: '2026-03-31T10:00:00+00:00' completed_at: '2026-03-31T10:00:18+00:00' processing_time_ms: 18420 document: filename: report.pdf page_count: 3 file_size_bytes: 245120 mime_type: application/pdf result: pages: - index: 1 markdown: |- # Report ... - index: 2 markdown: |- ## Section 2 ... - index: 3 markdown: |- ## Section 3 ... usage: pages_processed: 3 progress: percentage: 100 pages_processed: 3 error: null summary: Completed — terminal success description: >- Terminal success. `result.pages` and `usage.pages_processed` are populated; stop polling. Failed—TerminalFailure: value: id: parse_Kg status: failed created_at: '2026-03-31T10:00:00+00:00' completed_at: '2026-03-31T10:00:08+00:00' processing_time_ms: 5120 document: filename: report.pdf page_count: null file_size_bytes: 245120 mime_type: application/pdf result: null usage: null progress: null error: message: Parsing failed. summary: Failed — terminal failure description: >- Terminal failure. `error.message` carries the failure reason; stop polling. description: >- Async parse job status and (once terminal) result. `status` is `pending`/`processing` while in flight, `completed` on success, `failed` on failure. The `result` and `usage` blocks are populated only on success; the `error` block is populated only on failure. '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: >- Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '404': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: NotFound: value: id: null code: 404 error: not_found detail: The requested resource was not found. doc_url: https://developers.lighton.ai/errors#not_found summary: Not Found description: The requested resource was not found '429': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: TooManyRequests: value: id: null code: 429 error: too_many_requests detail: Too many requests. Please try again later. doc_url: https://developers.lighton.ai/errors#too_many_requests summary: Too Many Requests description: Too many requests security: - bearerAuth: [] components: schemas: ParseJobStatus: type: object description: >- Returned by ``GET /api/v3/parse/`` — async parse job status + (once terminal) result. Same shape as the sync ``ParseResponseSerializer`` but with completion fields (``result``, ``usage``, ``completed_at``, ``processing_time_ms``, ``document.page_count``) allowed to be null while the job is still in flight, plus an ``error`` block populated only on terminal failure. properties: id: type: string status: type: string created_at: type: string format: date-time completed_at: type: - string - 'null' format: date-time processing_time_ms: type: - integer - 'null' document: oneOf: - $ref: '#/components/schemas/ParseDocument' - type: 'null' result: oneOf: - $ref: '#/components/schemas/ParseResult' - type: 'null' usage: oneOf: - $ref: '#/components/schemas/ParseUsage' - type: 'null' progress: oneOf: - $ref: '#/components/schemas/ParseProgress' - type: 'null' error: oneOf: - $ref: '#/components/schemas/ParseError' - type: 'null' required: - completed_at - created_at - document - error - id - processing_time_ms - progress - result - status - usage APIV3ErrorResponse: type: object properties: id: type: - string - 'null' description: >- Job/resource id when one already exists (useful for async error diagnosis); null otherwise. code: type: integer description: HTTP status code error: type: string description: Error code used by the UI as a translation key detail: type: string description: Human-readable error message for developers doc_url: type: string description: Link to the error-code documentation page required: - code - detail - doc_url - error - id ParseDocument: type: object properties: filename: type: string page_count: type: - integer - 'null' file_size_bytes: type: integer mime_type: type: string required: - file_size_bytes - filename - mime_type - page_count ParseResult: type: object properties: pages: type: array items: $ref: '#/components/schemas/Page' required: - pages ParseUsage: type: object properties: pages_processed: type: integer required: - pages_processed ParseProgress: type: object description: Live progress while a polled async job is in flight. properties: percentage: type: integer description: Completion percentage [0, 100]. pages_processed: type: integer description: Pages parsed so far. required: - pages_processed - percentage ParseError: type: object description: Failure details surfaced on terminal-failed async parse jobs. properties: message: type: string required: - message Page: type: object description: >- Canonical per-page document text object. Originates with /parse and is reused by /ocr and /files (the latter imports it from here) so a client can switch between live parsing and reading an already-ingested file without reshaping page data. Defined once and reused everywhere — never redefine this shape per app. Extensible: future per-page fields (tables, images, confidence, ...) can be added here without breaking callers that only consume ``index`` + ``markdown``. properties: index: type: integer description: Page number within the document (1-based). markdown: type: string description: Page text rendered as Markdown. required: - index - markdown securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer authentication header of the form `Bearer `, where `` is your auth token. ````