openapi: 3.0.3
info:
  title: Factset Analytics Datastore About Batch Status API
  description: Allow clients to fetch precalculated Analytics through predeterministic URLs.
  contact:
    name: FactSet Research Systems
    url: https://developer.factset.com/contact
    email: api@factset.com
  license:
    name: Apache License, Version 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 1.0.0
servers:
- url: https://api.factset.com
  description: Production
- url: https://api-sandbox.factset.com
  description: Sandbox
security:
- basicAuth: []
tags:
- name: Batch Status
paths:
  /v1/batch-status:
    get:
      summary: Factset Returns the status for a Batch Request
      description: "Return the status for the underlying batch request that is specified by the id.\n\n  The Formula API supports Long Running asynchronous requests up to **20 minutes** via the `batch` parameter in the `/time-series` endpoint and up to **10 minutes** in the `/cross-sectional` endpoint.\n\n  *This feature is available to Individual Users subscribed to the Performance Package and Performance Package Plus Performance Tiers and all Production Users. If you are unsure which Performance Tier you are subscribed to or you would like to gain access to the batch capabilities, please contact your FactSet Account Team or \"Report Issue\" above and our support teams can assist.*\n"
      tags:
      - Batch Status
      operationId: getBatchStatus
      parameters:
      - $ref: '#/components/parameters/batchId'
      responses:
        '201':
          description: Batch Request has been completed and the response has been created.
          headers:
            Location:
              description: Path to Batch Request result.
              schema:
                type: string
              example: batch/v1/result?id=2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
              examples:
                Batch Status Done:
                  $ref: '#/components/examples/BatchStatusDoneResponse'
        '202':
          description: Batch Request has not finished and the result has NOT been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
              examples:
                Batch Status Queued:
                  $ref: '#/components/examples/BatchStatusQueuedResponse'
                Batch Status Executing:
                  $ref: '#/components/examples/BatchStatusExecutingResponse'
                Batch Status Failed - Timeout:
                  $ref: '#/components/examples/BatchStatusFailedResponseTimeout'
                Batch Status Failed - Memory Limit:
                  $ref: '#/components/examples/BatchStatusFailedResponseMemoryLimit'
                Batch Status Failed - Other:
                  $ref: '#/components/examples/BatchStatusFailedResponseOther'
        '404':
          description: Not Found
          headers:
            api-version:
              $ref: '#/components/headers/api-version'
            api-supported-versions:
              $ref: '#/components/headers/api-supported-versions'
            api-deprecated-versions:
              $ref: '#/components/headers/api-deprecated-versions'
            chain-id:
              $ref: '#/components/headers/chain-id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_detail'
              example:
                id: 5EFCCA8940CAEB6E
                code: batchRequestNotFound
                title: The Batch Request was not found. It has probably expired.
                timeStamp: '2019-11-01 11:09:41.918'
      deprecated: false
    post:
      summary: Factset Returns the status for a Batch Request
      description: "Return the status for the underlying batch request that is specified by the id.\n\n  The Formula API supports Long Running asynchronous requests up to **20 minutes** via the `batch` parameter in the `/time-series` endpoint and up to **10 minutes** in the `/cross-sectional` endpoint.\n\n  *This feature is available to Individual Users subscribed to the Performance Package and Performance Package Plus Performance Tiers and all Production Users. If you are unsure which Performance Tier you are subscribed to or you would like to gain access to the batch capabilities, please contact your FactSet Account Team or \"Report Issue\" above and our support teams can assist.*\n"
      tags:
      - Batch Status
      operationId: getBatchStatusWithPost
      responses:
        '201':
          description: Batch Request has been completed and the response has been created.
          headers:
            Location:
              description: Path to Batch Request result.
              schema:
                type: string
              example: batch/v1/result?id=2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
              examples:
                Batch Status Done:
                  $ref: '#/components/examples/BatchStatusDoneResponse'
        '202':
          description: Batch Request has not finished and the result has NOT been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
              examples:
                Batch Status Queued:
                  $ref: '#/components/examples/BatchStatusQueuedResponse'
                Batch Status Executing:
                  $ref: '#/components/examples/BatchStatusExecutingResponse'
                Batch Status Failed - Timeout:
                  $ref: '#/components/examples/BatchStatusFailedResponseTimeout'
                Batch Status Failed - Memory Limit:
                  $ref: '#/components/examples/BatchStatusFailedResponseMemoryLimit'
                Batch Status Failed - Other:
                  $ref: '#/components/examples/BatchStatusFailedResponseOther'
        '404':
          description: Not Found
          headers:
            api-version:
              $ref: '#/components/headers/api-version'
            api-supported-versions:
              $ref: '#/components/headers/api-supported-versions'
            api-deprecated-versions:
              $ref: '#/components/headers/api-deprecated-versions'
            chain-id:
              $ref: '#/components/headers/chain-id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_detail'
              example:
                id: 5EFCCA8940CAEB6E
                code: batchRequestNotFound
                title: The Batch Request was not found. It has probably expired.
                timeStamp: '2019-11-01 11:09:41.918'
      deprecated: false
      requestBody:
        $ref: '#/components/requestBodies/batch-status-postBody'
  /batch-status:
    get:
      tags:
      - Batch Status
      summary: Factset Returns the status for a Batch Request
      description: Return the status for the underlying batch request that is specified by the id.
      operationId: getBatchStatus
      parameters:
      - $ref: '#/components/parameters/batchId'
      responses:
        '201':
          description: The batch Request has been completed and the response has been created.
          headers:
            Location:
              description: Path to Batch Request result.
              schema:
                type: string
              example: batch-result?id=2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
              examples:
                Batch Status Done:
                  $ref: '#/components/examples/BatchStatusDoneResponse_2'
        '202':
          description: The batch Request has not finished and the result has NOT been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
              examples:
                Batch Status Queued:
                  $ref: '#/components/examples/BatchStatusQueuedResponse_2'
                Batch Status Executing:
                  $ref: '#/components/examples/BatchStatusExecutingResponse_2'
                Batch Status Failed:
                  $ref: '#/components/examples/BatchStatusFailedResponse'
        '404':
          $ref: '#/components/responses/404'
      deprecated: false
components:
  examples:
    BatchStatusQueuedResponse_2:
      description: Batch Status Queued Response
      value:
        data:
          id: 2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
          status: queued
          startTime: '2021-06-29T18:34:52.168Z'
          endTime: null
          error: null
    BatchStatusFailedResponseOther:
      description: Batch Status Failed Response - Other. The example response shows the result of checking the status of a batch request that failed unexpectedly. If you encounter this error, please contact FactSet support.
      value:
        data:
          id: 43839790-a64e-452a-b8f0-fc26117bd9f4
          status: FAILED
          startTime: '2023-09-20T13:37:13.653411'
          endTime: '2023-09-20T13:38:25.841134'
          error: Something went wrong. Contact FactSet for support.
    BatchStatusFailedResponseTimeout:
      description: Batch Status Failed Response - Timeout. The example response shows the result of checking the status of a batch request that took longer than 20 minutes to calculate and timed out.
      value:
        data:
          id: 2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
          status: FAILED
          startTime: '2021-06-29T18:34:52.168Z'
          endTime: '2021-06-29T18:44:55.402Z'
          error: timeout
    notFound:
      summary: Not Found
      description: The requested item was not found.
      value:
        status: Not Found
        timestamp: '2020-06-12T16:08:51.731Z'
        path: /factset-fundamentals/v2/{endpoint}
        message: The Batch Request was not found. It has probably expired.
        subErrors: null
    BatchStatusFailedResponseMemoryLimit:
      description: Batch Status Failed Response - MemoryLimit. The example response shows the result of checking the status of a batch request that exceeded the memory limit.
      value:
        data:
          id: 0a0452e2-3937-441d-b376-f2733a938587
          status: FAILED
          startTime: '2023-09-15T00:07:46.501947'
          endTime: '2023-09-15T00:08:53.936218'
          error: The request size is too large. Try again with a smaller request.
    BatchStatusFailedResponse:
      description: Batch Status Failed Response
      value:
        data:
          id: 2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
          status: failed
          startTime: '2021-06-29T18:34:52.168Z'
          endTime: '2021-06-29T18:34:55.402Z'
          error:
            id: 2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
            code: GenericError
            title: the date parameter must be in YYYY-MM-DD format
    BatchStatusDoneResponse:
      description: Batch Status Done Response
      value:
        data:
          id: 2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
          status: DONE
          startTime: '2021-06-29T18:34:52.168Z'
          endTime: '2021-06-29T18:34:55.402Z'
          error: null
    BatchStatusQueuedResponse:
      description: Batch Status Queued Response
      value:
        data:
          id: 2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
          status: QUEUED
          startTime: '2021-06-29T18:34:52.168Z'
          endTime: null
          error: null
    BatchStatusExecutingResponse_2:
      description: Batch Status Executing Response
      value:
        data:
          id: 2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
          status: executing
          startTime: '2021-06-29T18:34:52.168Z'
          endTime: null
          error: null
    BatchStatusDoneResponse_2:
      description: Batch Status Done Response
      value:
        data:
          id: 2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
          status: created
          startTime: '2021-06-29T18:34:52.168Z'
          endTime: '2021-06-29T18:34:55.402Z'
          error: null
    BatchStatusExecutingResponse:
      description: Batch Status Executing Response
      value:
        data:
          id: 2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
          status: EXECUTING
          startTime: '2021-06-29T18:34:52.168Z'
          endTime: null
          error: null
  parameters:
    batchId:
      name: id
      in: query
      description: Batch Request identifier.
      schema:
        type: string
        format: uuid
      required: true
      allowEmptyValue: false
  schemas:
    BatchStatus:
      title: Batch Status
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: the id of batch request.
        startTime:
          type: string
          nullable: true
          format: date-time
          description: Time when the batch request is started. This is in Eastern Time Zone. The date-time format is expressed as [YYYY-MM-DD]T[HH:MM:SSS], following ISO 8601.
        endTime:
          type: string
          nullable: true
          format: date-time
          description: Time when the batch request is ended. This is in Eastern Time Zone. The date-time format is expressed as [YYYY-MM-DD]T[HH:MM:SSS], following ISO 8601.
        status:
          type: string
          enum:
          - QUEUED
          - EXECUTING
          - DONE
          - FAILED
        error:
          type: string
          nullable: true
          example: The parameter 'formulas' is required and may not be empty.
          description: Error message.
    errorResponse:
      type: object
      title: Error Response
      description: Error Default Response
      properties:
        errors:
          type: array
          description: An array containing errors
          items:
            $ref: '#/components/schemas/errorObject'
    errorObject:
      type: object
      properties:
        id:
          description: A UUID for this particular occurrence of the problem.
          type: string
          example: adb01824-252f-4420-b0c6-35a1e3507ef5
        code:
          description: status
          type: string
          example: Bad Request
        links:
          description: The Endpoint path {package}/version/{endpoint}
          type: object
          properties:
            about:
              description: details.
              type: string
              example: /factset-fundamentals/v1/{endpoint}
        title:
          description: The plain text error message
          type: string
          example: Validation Error
    BatchDataRequest:
      title: Batch Data Request
      type: object
      required:
      - data
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              format: uuid
              example: 2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
              description: Batch Request identifier.
    error_detail:
      title: Error Object
      description: '`Error Object` is the response returned for an unsuccessful request.

        '
      type: object
      properties:
        id:
          description: Unique identifier for the request. Also known as the chain id.
          type: string
          example: 5EFCCA8940CAEA6B
          nullable: true
        code:
          description: Textual error code
          type: string
          example: notAuthenticated
          nullable: true
        title:
          description: A short, human-readable summary of the problem
          type: string
          example: There were either no, invalid, or expired credentials present in the request.
          nullable: true
        timestamp:
          description: timestamp in YYYY-MM-DD HH:MM:SS.SSS
          type: string
          format: date-time
          example: '2020-08-01 11:09:41.918'
          nullable: true
    BatchStatusResponse:
      title: Batch Status Response
      type: object
      properties:
        data:
          $ref: '#/components/schemas/BatchStatus'
  headers:
    chain-id:
      description: Unique identifier for the request. Also known as the chain id.
      schema:
        type: string
        example: 5EFCCA8940CAEA6B
    api-version:
      description: the full semantic version of the API.
      schema:
        type: string
        example: 1.0.0
    api-supported-versions:
      description: the comma-separated list of supported major versions.
      schema:
        type: string
        example: '1'
    api-deprecated-versions:
      description: the comma-separated list of deprecated major versions.
      schema:
        type: string
        example: 1,2
  responses:
    '404':
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Batch Request Not Found:
              $ref: '#/components/examples/notFound'
  requestBodies:
    batch-status-postBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BatchDataRequest'
          examples:
            BatchStatusRequest:
              summary: Batch Status Request
              value:
                data:
                  id: 2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  url: https://developer.factset.com/api-catalog/analytics-datastore-api
  description: API Documentation