> ## Documentation Index
> Fetch the complete documentation index at: https://developer.box.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Document Split job by ID

> Returns details for a single Document Split job identified by its ID, including the current status, the input definition, and any output files produced by the job.

> [!NOTE]
>
> Learn more about [Box SDK versioning strategy](https://developer.box.com/guides/tooling/sdks/sdk-versioning.md).


## OpenAPI

````yaml box-openapi-v2026.0.json GET /document_splits/{document_split_id}
openapi: 3.0.2
info:
  title: Box Platform API
  description: >-
    [Box Platform](https://developer.box.com) provides functionality to provide
    access to content stored within [Box](https://box.com). It provides
    endpoints for basic manipulation of files and folders, management of users
    within an enterprise, as well as more complex topics such as legal holds and
    retention policies.
  termsOfService: https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9
  contact:
    name: Box, Inc
    url: https://developer.box.com
    email: devrel@box.com
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: '2026.0'
  x-box-commit-hash: 0274a35f73
servers:
  - url: https://api.box.com/2.0
    description: Box Platform API server.
security:
  - OAuth2Security: []
tags:
  - name: Automate Workflows
    description: Endpoints for listing and manually starting Automate workflow actions.
    x-box-tag: automate_workflows
  - name: Convert to Box Note
    description: Create Box Notes from supported source content (for example Markdown).
    x-box-tag: notes
  - name: Document Split
    description: >-
      A set of endpoints used to split a paginated source document into multiple
      files based on user-defined or AI-generated page ranges.
    x-box-tag: document_split
  - name: Query
    description: Query for your items.
    x-box-tag: query
  - name: Shuttle
    description: >-
      Endpoints for managing Box Shuttle, the service that migrates content into
      Box from external sources. Use these endpoints to manage the systems that
      Shuttle migrates content from and the migration jobs that Shuttle runs.
    x-box-tag: shuttle
externalDocs:
  description: Box Developer Documentation.
  url: https://developer.box.com
paths:
  /document_splits/{document_split_id}:
    get:
      tags:
        - Document Split
      summary: Get Document Split job by ID
      description: >-
        Returns details for a single Document Split job identified by its ID,
        including the current status, the input definition, and any output files
        produced by the job.
      operationId: get_document_splits_id_v2026.0
      parameters:
        - $ref: '#/components/parameters/BoxVersionHeader'
        - name: document_split_id
          in: path
          description: The unique identifier for the Document Split job.
          required: true
          schema:
            type: string
          example: '1748426'
      responses:
        '200':
          description: Returns the Document Split job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentSplit'
        '401':
          description: >-
            Returned when the access token provided in the `Authorization`
            header is not recognized or not provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '403':
          description: >-
            Returned when the authenticated user does not have access to the
            Document Generation feature.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: >-
            Returned when the Document Split job is not found or the user does
            not have access to it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '429':
          description: >-
            Returned when the user has sent too many requests in a given amount
            of time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  parameters:
    BoxVersionHeader:
      name: box-version
      in: header
      description: Version header.
      allowEmptyValue: false
      required: true
      schema:
        type: string
        enum:
          - '2026.0'
      example: '2026.0'
  schemas:
    DocumentSplit:
      description: >-
        A standard representation of a Document Split job. The job represents a
        request to split a paginated source document into multiple files based
        on either a manual set of page ranges, a non-linear page selection, or a
        smart prompt-driven analysis.
      type: object
      properties:
        id:
          description: The unique identifier for the Document Split job.
          type: string
          example: '1748426'
        type:
          description: The value will always be `document_split`.
          type: string
          example: document_split
          enum:
            - document_split
        source_file:
          allOf:
            - $ref: '#/components/schemas/FileReference'
            - description: The file to split.
        status:
          description: The current state of the Document Split job.
          type: string
          example: submitted
          enum:
            - submitted
            - completed
            - failed
            - completed_with_error
        split_input:
          allOf:
            - $ref: '#/components/schemas/DocumentSplitCreateRequestType'
            - description: >-
                The caller-supplied input that was used to perform the split.
                The shape mirrors the request: for a `manual` split,
                `split_input` contains `split_type` and `split_definition`; for
                a `page_selection` split, `split_input` contains `split_type`
                and `page_selection`; for a `smart` split, `split_input`
                contains `split_type` and the caller-supplied `prompt`. For
                smart splits, the page ranges that Box produced are exposed
                under `output.split_definition`.
        output:
          description: >-
            The result of the Document Split job. `null` until the job has
            produced output.
          oneOf:
            - $ref: '#/components/schemas/DocumentSplitOutput'
            - title: OpenAPI 3.0 null schema type
              description: The definition for a null schema type in OpenAPI `3.0`.
              type: object
              nullable: true
              additionalProperties: false
        destination_folder:
          allOf:
            - $ref: '#/components/schemas/FolderReference'
            - description: The folder that received the generated files.
        input_source:
          description: >-
            The system that initiated the request, used for analytics and
            traceability.
          type: string
          example: api
          enum:
            - api
            - box
            - relay
            - salesforce
        created_at:
          description: When the Document Split job was created.
          type: string
          format: date-time
          example: '2023-10-26T15:30:00Z'
        created_by:
          allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who created the Document Split job.
        enterprise:
          allOf:
            - $ref: '#/components/schemas/EnterpriseReference'
            - description: The enterprise that owns the Document Split job.
        failures:
          description: >-
            Errors and warnings that occurred during the document split. `null`
            when no failures were recorded.
          oneOf:
            - $ref: '#/components/schemas/DocumentSplitFailures'
            - title: OpenAPI 3.0 null schema type
              description: The definition for a null schema type in OpenAPI `3.0`.
              type: object
              nullable: true
              additionalProperties: false
        external_id:
          description: >-
            An optional identifier supplied by the caller when the Document
            Split job was created. Returned for correlation only. It is not a
            Box resource ID, is not required to be unique, and cannot be used to
            look up the job.
          type: string
          example: invoice-48291
          maxLength: 255
      required:
        - id
        - type
        - source_file
        - destination_folder
        - status
        - split_input
        - input_source
      title: Document Split
      x-box-resource-id: document_split_v2026.0
      x-box-tag: document_split
    ClientError:
      description: A generic error.
      type: object
      properties:
        type:
          description: The value will always be `error`.
          type: string
          example: error
          enum:
            - error
          nullable: false
        status:
          description: The HTTP status of the response.
          type: integer
          format: int32
          example: 400
          nullable: false
        code:
          description: A Box-specific error code.
          type: string
          example: item_name_invalid
          enum:
            - created
            - accepted
            - no_content
            - redirect
            - not_modified
            - bad_request
            - unauthorized
            - forbidden
            - not_found
            - method_not_allowed
            - conflict
            - precondition_failed
            - too_many_requests
            - internal_server_error
            - unavailable
            - item_name_invalid
            - insufficient_scope
        message:
          description: A short message describing the error.
          type: string
          example: Method Not Allowed
          nullable: false
        context_info:
          description: >-
            A free-form object that contains additional context about the error.
            The possible fields are defined on a per-endpoint basis. `message`
            is only one example.
          type: object
          example:
            message: Something went wrong
          additionalProperties: {}
          nullable: true
        help_url:
          description: A URL that links to more information about why this error occurred.
          type: string
          example: >-
            https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
          nullable: false
        request_id:
          description: >-
            A unique identifier for this response, which can be used when
            contacting Box support.
          type: string
          example: abcdef123456
          nullable: false
      title: Client error
      x-box-resource-id: client_error_v2026.0
    FileReference:
      description: File reference.
      type: object
      properties:
        type:
          description: The value will always be `file`.
          type: string
          example: file
          enum:
            - file
          nullable: false
        id:
          description: ID of the file.
          type: string
          example: '42037322'
          nullable: false
      required:
        - type
        - id
      title: File reference
    DocumentSplitCreateRequestType:
      description: Validation rules for the supported Document Split create request types.
      oneOf:
        - $ref: '#/components/schemas/DocumentSplitCreateRequestManual'
        - $ref: '#/components/schemas/DocumentSplitCreateRequestPageSelection'
        - $ref: '#/components/schemas/DocumentSplitCreateRequestSmart'
      title: Document Split create request type
      x-box-tag: document_split
    DocumentSplitOutput:
      description: The set of files produced by a completed Document Split job.
      type: object
      properties:
        generated_files:
          description: References to the files that were created by the split.
          type: array
          items:
            $ref: '#/components/schemas/FileReference'
        split_definition:
          description: >-
            The page ranges that Box produced for a `smart` split. Each entry
            corresponds to one generated file with the inclusive page range
            `[start, end]`. Omitted or `null` for `manual` splits, where the
            caller-supplied ranges are available in
            `split_input.split_definition`. Omitted for `page_selection` splits,
            where the caller-supplied page layout is available in
            `split_input.page_selection`.
          type: array
          items:
            $ref: '#/components/schemas/DocumentSplitPageRange'
          example:
            - start: 1
              end: 10
            - start: 11
              end: 25
          nullable: true
      title: Document Split output
      x-box-resource-id: document_split_output_v2026.0
      x-box-tag: document_split
    FolderReference:
      description: Folder reference.
      type: object
      properties:
        type:
          description: The value will always be `folder`.
          type: string
          example: folder
          enum:
            - folder
          nullable: false
        id:
          description: ID of the folder.
          type: string
          example: '42037322'
      required:
        - type
        - id
      title: Folder reference
    User--Mini:
      description: >-
        A mini representation of a user, as can be returned when nested within
        other resources.
      type: object
      allOf:
        - $ref: '#/components/schemas/User--Base'
        - properties:
            name:
              description: The display name of this user.
              type: string
              example: Aaron Levie
              maxLength: 50
            login:
              description: The primary email address of this user.
              type: string
              format: email
              example: ceo@example.com
      title: User (Mini)
    EnterpriseReference:
      description: A reference to an enterprise, used when nested within another resource.
      type: object
      properties:
        id:
          description: The unique identifier for this enterprise.
          type: string
          example: '1910967'
        type:
          description: The value will always be `enterprise`.
          type: string
          example: enterprise
          enum:
            - enterprise
          nullable: false
      required:
        - type
        - id
      title: Enterprise reference
    DocumentSplitFailures:
      description: Errors and warnings that occurred during a Document Split job.
      allOf:
        - $ref: '#/components/schemas/DocumentFailures'
      title: Document Split failures
      x-box-resource-id: document_split_failures_v2026.0
      x-box-tag: document_split
    DocumentSplitCreateRequestManual:
      description: >-
        Validation rules for creating a Document Split job using caller-supplied
        page ranges.
      type: object
      properties:
        split_type:
          description: Discriminator. Must be `manual` for this variant.
          type: string
          example: manual
          enum:
            - manual
        version:
          description: >-
            The version of the manual split input format. Omitted or `v_1` is
            the legacy `split_definition` format. Existing clients may omit this
            field.
          type: string
          example: v_1
          enum:
            - v_1
        split_definition:
          description: >-
            Page ranges that define the split. Each entry produces one output
            file containing the inclusive page range `[start, end]`.
          type: array
          items:
            $ref: '#/components/schemas/DocumentSplitPageRange'
          example:
            - start: 1
              end: 5
            - start: 6
              end: 14
          minItems: 1
      not:
        anyOf:
          - required:
              - prompt
          - required:
              - page_selection
      required:
        - split_type
        - split_definition
      title: Document Split manual create request
      x-box-tag: document_split
    DocumentSplitCreateRequestPageSelection:
      description: >-
        Validation rules for creating a Document Split job using non-linear page
        selections. Each item produces one output file from the declared page
        segments.
      type: object
      properties:
        split_type:
          description: Discriminator. Must be `page_selection` for this variant.
          type: string
          example: page_selection
          enum:
            - page_selection
        version:
          description: >-
            The version of the page selection input format. Optional. When
            provided must be `v_2`.
          type: string
          example: v_2
          enum:
            - v_2
        page_selection:
          $ref: '#/components/schemas/DocumentSplitPageSelection'
      not:
        anyOf:
          - required:
              - prompt
          - required:
              - split_definition
      required:
        - split_type
        - page_selection
      title: Document Split page selection create request
      x-box-tag: document_split
    DocumentSplitCreateRequestSmart:
      description: >-
        Validation rules for creating a Document Split job using Box-generated
        page ranges guided by a caller-supplied prompt.
      type: object
      properties:
        split_type:
          description: Discriminator. Must be `smart` for this variant.
          type: string
          example: smart
          enum:
            - smart
        prompt:
          description: >-
            A natural language prompt that guides automatic page range
            detection.
          type: string
          example: Split this contract into one file per signed section.
          minLength: 1
      not:
        anyOf:
          - required:
              - split_definition
          - required:
              - page_selection
      required:
        - split_type
        - prompt
      title: Document Split smart create request
      x-box-tag: document_split
    DocumentSplitPageRange:
      description: >-
        An inclusive page range used to define one slice of a manual Document
        Split job.
      type: object
      properties:
        start:
          description: The first page (inclusive) included in this slice.
          type: integer
          format: int32
          example: 1
          minimum: 1
        end:
          description: The last page (inclusive) included in this slice.
          type: integer
          format: int32
          example: 10
          minimum: 1
      additionalProperties: false
      required:
        - start
        - end
      title: Document Split page range
      x-box-tag: document_split
    User--Base:
      description: >-
        A mini representation of a user, used when nested within another
        resource.
      type: object
      properties:
        id:
          description: The unique identifier for this user.
          type: string
          example: '11446498'
        type:
          description: The value will always be `user`.
          type: string
          example: user
          enum:
            - user
          nullable: false
      required:
        - type
        - id
      title: User (Base)
    DocumentFailures:
      description: Errors and warnings that occurred during a document job.
      type: object
      properties:
        errors:
          description: A list of errors that occurred during the document job.
          type: array
          items:
            type: string
          example:
            - The source file could not be processed.
        warnings:
          description: A list of warnings that occurred during the document job.
          type: array
          items:
            type: string
          example:
            - Some pages were skipped because they were blank.
      required:
        - errors
        - warnings
      title: Document failures
    DocumentSplitPageSelection:
      description: >-
        Defines a non-sequential page selection for a Document Split job. Each
        item in the array produces one output PDF assembled from the declared
        page segments.
      type: array
      items:
        $ref: '#/components/schemas/DocumentSplitPageSelectionItem'
      example:
        - name: exhibits
          segments:
            - type: single_page
              page: 4
            - type: single_page
              page: 8
            - type: page_range
              start: 6
              end: 8
      minItems: 1
      title: Document Split page selection
      x-box-tag: document_split
    DocumentSplitPageSelectionItem:
      description: >-
        A single output file definition within a page selection request. Each
        item produces one PDF containing the pages specified by its segments
        array.
      type: object
      properties:
        name:
          description: >-
            Optional name for the output file (without extension). When omitted
            the system generates a sequential name based on the source file
            name.
          type: string
          example: exhibits
          minLength: 1
        segments:
          description: >-
            An ordered list of page segments to include in this output file.
            Each segment specifies either a single page or a contiguous page
            range.
          type: array
          items:
            $ref: '#/components/schemas/DocumentSplitPageSelectionSegment'
          example:
            - type: single_page
              page: 4
            - type: page_range
              start: 6
              end: 8
          minItems: 1
      required:
        - segments
      title: Document Split page selection item
      x-box-tag: document_split
    DocumentSplitPageSelectionSegment:
      description: >-
        A single page segment within a page selection item. The `type` field
        identifies whether the segment is a single page or an inclusive page
        range.
      oneOf:
        - $ref: '#/components/schemas/DocumentSplitPageSelectionSinglePage'
        - $ref: '#/components/schemas/DocumentSplitPageSelectionPageRange'
      title: Document Split page selection segment
      x-box-tag: document_split
    DocumentSplitPageSelectionSinglePage:
      description: >-
        A page selection segment that includes a single page from the source
        document.
      type: object
      properties:
        type:
          description: Discriminator. Must be `single_page` for this variant.
          type: string
          example: single_page
          enum:
            - single_page
        page:
          description: A single page number to include.
          type: integer
          format: int32
          example: 4
          minimum: 1
      additionalProperties: false
      required:
        - type
        - page
      title: Document Split page selection single page
      x-box-tag: document_split
    DocumentSplitPageSelectionPageRange:
      description: >-
        A page selection segment that includes an inclusive page range from the
        source document.
      type: object
      properties:
        type:
          description: Discriminator. Must be `page_range` for this variant.
          type: string
          example: page_range
          enum:
            - page_range
        start:
          description: The first page (inclusive) included in this segment.
          type: integer
          format: int32
          example: 6
          minimum: 1
        end:
          description: The last page (inclusive) included in this segment.
          type: integer
          format: int32
          example: 8
          minimum: 1
      additionalProperties: false
      required:
        - type
        - start
        - end
      title: Document Split page selection page range
      x-box-tag: document_split
  securitySchemes:
    OAuth2Security:
      type: oauth2
      description: >-
        The access token received from the authorization server in the OAuth 2.0
        flow.
      flows:
        authorizationCode:
          authorizationUrl: https://account.box.com/api/oauth2/authorize
          tokenUrl: https://api.box.com/oauth2/token
          scopes:
            root_readonly: Read all files and folders stored in Box
            root_readwrite: Read and write all files and folders stored in Box
            manage_app_users: Provision and manage app users
            manage_managed_users: Provision and manage managed users
            manage_groups: Manage an enterprise's groups
            manage_webhook: Create webhooks programmatically through the API
            manage_enterprise_properties: Manage enterprise properties
            manage_data_retention: Manage data retention polices
            manage_legal_hold: Manage Legal Holds

````