Factset Batch Result API

openapi: 3.0.3
info:
  title: Factset Analytics Datastore About Batch Result 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 Result
paths:
  /v1/batch-result:
    get:
      summary: Factset Returns the response for a Batch Request
      description: "Returns the response data 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 Result
      operationId: getBatchData
      parameters:
      - $ref: '#/components/parameters/batchId'
      responses:
        '200':
          description: Request Response Object when batch request has completed and response is created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchDataResponse'
              examples:
                Time-Series Single Id and Single Data Item:
                  $ref: '#/components/examples/time-series-singleId-singleItem'
                Cross-Sectional Single Id and Single Data Item:
                  $ref: '#/components/examples/cross-sectional-singleId-singleItem'
        '202':
          description: Batch Request has not finished and the result has NOT been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
              examples:
                Batch Request Queued:
                  $ref: '#/components/examples/BatchResultQueuedResponse'
                Batch Request Executing:
                  $ref: '#/components/examples/BatchResultExecutingResponse'
        '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: "Returns the response data 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 Result
      operationId: getBatchDataWithPost
      responses:
        '200':
          description: Request Response Object when batch request has completed and response is created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchDataResponse'
              examples:
                Time-Series Single Id and Single Data Item:
                  $ref: '#/components/examples/time-series-singleId-singleItem'
                Cross-Sectional Single Id and Single Data Item:
                  $ref: '#/components/examples/cross-sectional-singleId-singleItem'
        '202':
          description: Batch Request has not finished and the result has NOT been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
              examples:
                Batch Request Queued:
                  $ref: '#/components/examples/BatchResultQueuedResponse'
                Batch Request Executing:
                  $ref: '#/components/examples/BatchResultExecutingResponse'
        '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-result-postBody'
  /batch-result:
    get:
      tags:
      - Batch Result
      summary: Factset Returns the response for a Batch Request
      description: 'Returns the response data for the underlying batch request that is specified by the id.


        By default, this endpoint will return data as JSON. If you wish to receive your data in CSV format, you can edit the header to have the "accept" parameter as "text/csv" instead of "application/json".

        '
      operationId: getBatchData
      parameters:
      - $ref: '#/components/parameters/batchId'
      responses:
        '200':
          description: Request Response Object when the batch request has been completed and the response is created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batchResultResponse'
              examples:
                Fundamentals endpoint response of Single Company (FDS-US), and Multiple Metrics (FF_SALES, FF_PE):
                  $ref: '#/components/examples/resultOfSingleIdwithMultipleMetricItem'
                Segments endpoint response of Single Company (AAPL-US), sales(SALES) details for the given period:
                  $ref: '#/components/examples/resultOfSingleIdwithSingleMetricItemSegment'
        '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 Request Queued:
                  $ref: '#/components/examples/BatchStatusQueuedResponse'
                Batch Request Executing:
                  $ref: '#/components/examples/BatchStatusExecutingResponse'
        '404':
          $ref: '#/components/responses/404'
      deprecated: false
components:
  examples:
    resultOfSingleIdwithMultipleMetricItem:
      summary: Result of Single Company and Multiple Metrics [FF_SALES, FF_PE]
      description: 'Results of the FDS-US Quarterly Sales and Price to Earnings data as of 2020-05-31

        '
      value:
        data:
        - requestId: FDS
          fsymId: SQFMK3-R
          metric: FF_SALES
          periodicity: QTR
          fiscalPeriod: 3
          fiscalYear: 2020
          fiscalPeriodLength: 92
          fiscalEndDate: '2020-05-31'
          reportDate: '2020-05-31'
          epsReportDate: '2020-06-25'
          updateType: Final
          currency: USD
          value: 374.083
        - requestId: FDS
          fsymId: SQFMK3-R
          metric: FF_PE
          periodicity: QTR
          fiscalPeriod: 3
          fiscalYear: 2020
          fiscalPeriodLength: 92
          fiscalEndDate: '2020-05-31'
          reportDate: '2020-05-31'
          epsReportDate: '2020-06-25'
          updateType: Final
          currency: USD
          value: 31.6769162623484
    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
    resultOfSingleIdwithSingleMetricItemSegment:
      summary: Result of Single Company single metric item [SALES] details.
      description: 'Results of the AAPL-US sales data for the period 2012-01-01 to 2014-01-01 on an annual basis with the preliminary data Values.

        '
      value:
        data:
        - requestId: AAPL-US
          fsymId: MH33D6-R
          metric: SALES
          date: 2012-09-28 00:00:00+00:00
          label: iPhone
          value: 141319
        - requestId: AAPL-US
          fsymId: MH33D6-R
          metric: SALES
          date: 2012-09-28 00:00:00+00:00
          label: iPad
          value: 19222
    time-series-singleId-singleItem:
      summary: Single Id and Single Data Item
      description: '`time-series` Request for Single Price Record for IBM

        '
      value:
        data:
        - error: 0
          formula: P_PRICE(0)
          requestId: IBM
          result:
            values:
            - 120.77
            dates:
            - '2020-07-09'
          dataType: DOUBLE
          objectType: TIMESERIES
    BatchResultQueuedResponse:
      description: Batch Result Queued Response
      value:
        errors:
          id: 618AC9B50DE76980
          code: Accepted
          title: Please check the status endpoint until the batch request has a status of DONE and then retrieve the results from the results endpoint.
          timestamp: '2022-01-18 18:29:59.189'
    BatchResultExecutingResponse:
      description: Batch Result Executing Response
      value:
        errors:
          id: 618AC9B50DE76980
          code: Accepted
          title: Please check the status endpoint until the batch request has a status of DONE and then retrieve the results from the results endpoint.
          timestamp: '2022-01-18 18:29:59.189'
    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:
      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
    cross-sectional-singleId-singleItem:
      summary: Single Equity Id and Single Equity Data Item
      description: '`cross-sectional` Request for Single Price Record for IBM

        '
      value:
        data:
        - dataItemName: requestId
          result:
          - IBM
          dataType: STRING
          error: 0
        - dataItemName: P_PRICE(0)
          result:
          - 120.77
          dataType: DOUBLE
          error: 0
  schemas:
    fundamentalValue:
      description: 'Value of the data metric requested. Note that the type of value is ''object'', and depending on the data metric requested, the value could be an object representation of a string or double. '
      oneOf:
      - type: string
        nullable: true
      - type: number
        format: double
        nullable: true
    batchResultResponse:
      title: Batch Data Response
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/batchResult'
    fundamental:
      title: Fundamental Object
      type: object
      required:
      - fiscalPeriod
      description: FactSet Fundamentals Response item
      properties:
        requestId:
          description: Identifier that was used for the request.
          type: string
          example: IBM-US
        fsymId:
          description: FactSet Regional Security Identifier. Six alpha-numeric characters, excluding vowels, with an -R suffix (XXXXXX-R). Identifies the security's best regional security data series per currency. For equities, all primary listings per region and currency are allocated a regional-level permanent identifier. The regional-level permanent identifier will be available once a SEDOL representing the region/currency has been allocated and the identifiers are on FactSet.
          type: string
          example: SJY281-R
          nullable: true
        metric:
          description: The requested `metric` input, representing the Fundamental Data Item. For a definition of the item please use the /fundamentals/v#/metrics endpoint.
          type: string
          example: FF_SALES
          nullable: true
        periodicity:
          description: Periodicity or frequency of the fiscal periods, where ANN = Annual Original, ANN_R = Annual Latest, QTR = Quarterly Original, QTR_R = Quarterly Latest, SEMI = Semi-Annual Original, SEMI_R = Semi-Annual Latest, LTM = Last Twelve Months Original, LTM_R = Last Twelve Months Latest, LTMSG = Last Twelve Months Global, [OA17959](https://my.apps.factset.com/oa/pages/17959), LTM_SEMI = Last Twelve Months - Semi-Annual Data and YTD = Year-to-date. Please note that the coverage for SEMI_R and LTM_R may be limited as fewer companies report with these periodicities.
          type: string
          example: QTR
          enum:
          - ANN
          - ANN_R
          - QTR
          - QTR_R
          - SEMI
          - SEMI_R
          - CAL
          - LTM
          - LTM_R
          - LTMSG
          - LTM_SEMI
          - YTD
          nullable: true
        fiscalPeriod:
          description: 'Fiscal Period indicator. Returns an integer representing the fiscal period for the requested item and periodicity. QUARTERLY CODE: 1-Fist Quarter; 2-Second Quarter; 3-Third Quarter; 4-Fourth Quarter. SEMI-CODE: 1-First Semi-annual Period; 2-Second Semi-annual Period.'
          type: integer
          example: 4
          nullable: true
        fiscalYear:
          description: Fiscal year of the reported period in YYYY format.
          type: integer
          example: 2018
          nullable: true
        fiscalPeriodLength:
          description: Length of the fiscal period in days.
          type: integer
          example: 91
          nullable: true
        fiscalEndDate:
          description: The normalized data the fiscal period ended.
          type: string
          format: date
          example: '2017-12-31'
          nullable: true
        reportDate:
          description: The date the reported fiscal period ended.
          type: string
          format: date
          example: '2017-12-30'
          nullable: true
        epsReportDate:
          description: The date the EPS was reported for the requested periodicity. In YYYY-MM-DD format. Unavailable data returned as 0001-01-01.
          type: string
          format: date
          example: '2018-02-24'
          nullable: true
        updateType:
          description: 'Update Type: Preliminary - The period is updated from a report that usually contains limited or only key information., Final - The period is updated from a report where detailed information is available in financial statements including the notes to the line items.'
          type: string
          example: Preliminary
          nullable: true
          enum:
          - Preliminary
          - Final
        currency:
          description: 'Currency code for the data. For a list of currency ISO codes, visit [Online Assistant Page #1470](https://oa.apps.factset.com/pages/1470).'
          type: string
          example: USD
          nullable: true
        value:
          $ref: '#/components/schemas/fundamentalValue'
    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.
    BatchData:
      title: Batch Data
      description: 'The schema for the batched result is determined by the endpoint you used with the _batch_ parameter.

        Please see the schema for that endpoint for the definition.

        '
      type: object
    errorResponse:
      type: object
      title: Error Response
      description: Error Default Response
      properties:
        errors:
          type: array
          description: An array containing errors
          items:
            $ref: '#/components/schemas/errorObject'
    batchResult:
      title: Batch Data
      oneOf:
      - $ref: '#/components/schemas/fundamental'
      - $ref: '#/components/schemas/segment'
    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
    segment:
      title: Segment Object
      type: object
      required:
      - label
      properties:
        requestId:
          description: Identifier that was used for the request.
          type: string
          example: AAPL-US
        fsymId:
          description: FactSet Regional Security Identifier. Six alpha-numeric characters, excluding vowels, with an -R suffix (XXXXXX-R). Identifies the security's best regional security data series per currency. For equities, all primary listings per region and currency are allocated a regional-level permanent identifier. The regional-level permanent identifier will be available once a SEDOL representing the region/currency has been allocated and the identifiers are on FactSet.
          type: string
          example: MH33D6-R
          nullable: true
        metric:
          description: The requested `metric` input, representing the Fundamental Data Item. For a definition of the item please use the /fundamentals/v#/metrics endpoint.
          type: string
          example: SALES
          nullable: true
        label:
          description: Report labels of the segment type requested.
          type: string
          example: iPhone
          nullable: true
        date:
          description: Date for the period requested expressed in YYYY-MM-DD format
          type: string
          format: date
          example: '2022-09-30'
          nullable: true
        value:
          $ref: '#/components/schemas/segmentValue'
    BatchStatusResponse:
      title: Batch Status Response
      type: object
      properties:
        data:
          $ref: '#/components/schemas/BatchStatus'
    BatchDataResponse:
      title: Batch Data Response
      type: object
      properties:
        data:
          $ref: '#/components/schemas/BatchData'
    segmentValue:
      description: 'Value of the data metric requested. Note that the type of value is ''object'', and depending on the data metric requested, the value could be an object representation of a string or double. '
      oneOf:
      - type: string
        nullable: true
      - type: number
        format: double
        nullable: true
  parameters:
    batchId:
      name: id
      in: query
      description: Batch Request identifier.
      schema:
        type: string
        format: uuid
      required: true
      allowEmptyValue: false
  requestBodies:
    batch-result-postBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BatchDataRequest'
          examples:
            BatchDataRequest:
              summary: Batch Result Request
              value:
                data:
                  id: 2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
  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'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  url: https://developer.factset.com/api-catalog/analytics-datastore-api
  description: API Documentation