llamaindex Jobs API

openapi: 3.2.0
info:
  title: LlamaIndex LlamaParse Jobs API
  description: LlamaParse is a GenAI-native document parsing API that transforms complex document data for downstream LLM use cases including agents, RAG pipelines, and data processing workflows. The v2 API provides endpoints for parsing via JSON requests (accepting file IDs or URLs) and multipart file uploads. It supports multiple parsing tiers including fast, cost-effective, agentic, and agentic-plus modes, and returns results asynchronously via job polling.
  version: '2.0'
  contact:
    name: LlamaIndex Support
    url: https://www.llamaindex.ai/contact
  termsOfService: https://www.llamaindex.ai/terms-of-service
servers:
- url: https://api.cloud.llamaindex.ai/api/v2
  description: US Production Server
- url: https://api.cloud.llamaindex.eu/api/v2
  description: EU Production Server
security:
- bearerAuth: []
tags:
- name: Jobs
  description: Monitor and retrieve results from asynchronous parsing jobs.
paths:
  /parse/jobs:
    get:
      operationId: listParseJobs
      summary: List parse jobs
      description: Retrieve a list of parse jobs for the authenticated project. Supports optional filtering and pagination to narrow down results.
      tags:
      - Jobs
      parameters:
      - name: project_id
        in: query
        description: Filter jobs by project identifier.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of jobs to return.
        required: false
        schema:
          type: integer
          minimum: 1
      - name: offset
        in: query
        description: Number of jobs to skip for pagination.
        required: false
        schema:
          type: integer
          minimum: 0
      responses:
        '200':
          description: Successfully retrieved list of parse jobs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ParseJob'
        '401':
          description: Unauthorized - invalid or missing API key
  /parse/jobs/{jobId}:
    get:
      operationId: getParseJob
      summary: Get parse job status
      description: Retrieve the status and optionally the results of a parse job. Use the expand parameter to control what parsed content is returned, including text, markdown, structured JSON, or metadata. Poll this endpoint to check job completion status.
      tags:
      - Jobs
      parameters:
      - $ref: '#/components/parameters/jobId'
      - name: expand
        in: query
        description: Comma-separated list of result fields to include in the response. Controls whether text, markdown, structured JSON, or metadata is returned with the job status.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved parse job status and results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParseJob'
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Parse job not found
  /parse/jobs/{jobId}/result:
    get:
      operationId: getParseJobResult
      summary: Get parse job result
      description: Retrieve the full parsed result of a completed parse job. Returns the extracted content in the requested format. The job must be in a completed state for results to be available.
      tags:
      - Jobs
      parameters:
      - $ref: '#/components/parameters/jobId'
      responses:
        '200':
          description: Successfully retrieved parse job result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParseResult'
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Parse job not found or not completed
components:
  schemas:
    ParseResult:
      type: object
      description: The parsed output of a document, containing extracted content in various formats.
      properties:
        text:
          type: string
          description: Plain text representation of the parsed content.
        markdown:
          type: string
          description: Markdown-formatted representation of the parsed content.
        json:
          type: object
          additionalProperties: true
          description: Structured JSON representation of the parsed content.
        pages:
          type: array
          description: Per-page parsing results.
          items:
            $ref: '#/components/schemas/ParsePage'
        metadata:
          type: object
          additionalProperties: true
          description: Metadata extracted from the document.
    ParseJob:
      type: object
      description: A parse job representing the asynchronous processing of a document.
      properties:
        id:
          type: string
          description: Unique identifier of the parse job.
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
          description: Current status of the parse job.
        tier:
          type: string
          enum:
          - fast
          - cost_effective
          - agentic
          - agentic_plus
          description: Parsing tier used for this job.
        file_name:
          type: string
          description: Name of the parsed file.
        num_pages:
          type: integer
          description: Total number of pages in the document.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the parse job was created.
        completed_at:
          type: string
          format: date-time
          description: Timestamp when the parse job completed, if applicable.
        result:
          $ref: '#/components/schemas/ParseResult'
    ParsePage:
      type: object
      description: Parsed content for a single page of a document.
      properties:
        page_number:
          type: integer
          minimum: 1
          description: 1-based page number.
        text:
          type: string
          description: Plain text content of the page.
        markdown:
          type: string
          description: Markdown-formatted content of the page.
  parameters:
    jobId:
      name: jobId
      in: path
      description: Unique identifier of the parse job.
      required: true
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: LlamaCloud API key obtained from the LlamaCloud dashboard. Include as a Bearer token in the Authorization header.
externalDocs:
  description: LlamaParse API v2 Guide
  url: https://developers.llamaindex.ai/python/cloud/llamaparse/api-v2-guide/