Factset Batch Result API

openapi: 3.2.0
info:
  title: Factset Batch Result API
  version: '1.0'
  description: 'Operations tagged Batch Result across 2 of this provider''s published API definitions: formula-openapi-original.yml, fundamentals-openapi-original.yml. Each path carries the servers of the definition it was published in.'
servers:
- description: Production
  url: https://api.factset.com/formula-api
- url: https://api.factset.com/content/factset-fundamentals/v2
  description: Production
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
      security:
      - BasicAuth: []
    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'
      security:
      - BasicAuth: []
    servers:
    - description: Production
      url: https://api.factset.com/formula-api
  /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
      security:
      - FactSetApiKey: []
      - FactSetOAuth2: []
    servers:
    - url: https://api.factset.com/content/factset-fundamentals/v2
      description: Production
components:
  schemas:
    BatchStatus:
      title: Batch Status
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: the id of batch request.
        startTime:
          type:
          - string
          - 'null'
          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
          - 'null'
          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
          - 'null'
          example: The parameter 'formulas' is required and may not be empty.
          description: Error message.
    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
          - 'null'
          example: 5EFCCA8940CAEA6B
        code:
          description: Textual error code
          type:
          - string
          - 'null'
          example: notAuthenticated
        title:
          description: A short, human-readable summary of the problem
          type:
          - string
          - 'null'
          example: There were either no, invalid, or expired credentials present in the request.
        timestamp:
          description: timestamp in YYYY-MM-DD HH:MM:SS.SSS
          type:
          - string
          - 'null'
          format: date-time
          example: '2020-08-01 11:09:41.918'
    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.
    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'
    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
    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
    BatchStatus_2:
      title: Batch Status
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: the id of batch request.
        startTime:
          type: string
          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
          - 'null'
          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
          - created
          - failed
        error:
          $ref: '#/components/schemas/batchErrorObject'
    batchResult:
      title: Batch Data
      oneOf:
      - $ref: '#/components/schemas/fundamental'
      - $ref: '#/components/schemas/segment'
    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
        - 'null'
      - type:
        - number
        - 'null'
        format: double
    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
        - 'null'
      - type:
        - number
        - 'null'
        format: double
    errorResponse:
      type: object
      title: Error Response
      description: Error Default Response
      properties:
        errors:
          type: array
          description: An array containing errors
          items:
            $ref: '#/components/schemas/errorObject'
    batchErrorObject:
      type:
      - object
      - 'null'
      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: GenericError
        title:
          description: The plain text error message
          type: string
          example: Validation Error
    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
          - 'null'
          example: SJY281-R
        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
          - 'null'
          example: FF_SALES
        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
          - 'null'
          example: QTR
          enum:
          - ANN
          - ANN_R
          - QTR
          - QTR_R
          - SEMI
          - SEMI_R
          - CAL
          - LTM
          - LTM_R
          - LTMSG
          - LTM_SEMI
          - YTD
        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
          - 'null'
          example: 4
        fiscalYear:
          description: Fiscal year of the reported period in YYYY format.
          type:
          - integer
          - 'null'
          example: 2018
        fiscalPeriodLength:
          description: Length of the fiscal period in days.
          type:
          - integer
          - 'null'
          example: 91
        fiscalEndDate:
          description: The normalized data the fiscal period ended.
          type:
          - string
          - 'null'
          format: date
          example: '2017-12-31'
        reportDate:
          description: The date the reported fiscal period ended.
          type:
          - string
          - 'null'
          format: date
          example: '2017-12-30'
        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
          - 'null'
          format: date
          example: '2018-02-24'
        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
          - 'null'
          example: Preliminary
          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
          - 'null'
          example: USD
        value:
          $ref: '#/components/schemas/fundamentalValue'
    batchResultResponse:
      title: Batch Data Response
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/batchResult'
    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
          - 'null'
          example: MH33D6-R
        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
          - 'null'
          example: SALES
        label:
          description: Report labels of the segment type requested.
          type:
          - string
          - 'null'
          example: iPhone
        date:
          description: Date for the period requested expressed in YYYY-MM-DD format
          type:
          - string
          - 'null'
          format: date
          example: '2022-09-30'
        value:
          $ref: '#/components/schemas/segmentValue'
  headers:
    api-deprecated-versions:
      description: the comma-separated list of deprecated major versions.
      schema:
        type: string
        example: 1,2
    api-supported-versions:
      description: the comma-separated list of supported major versions.
      schema:
        type: string
        example: '1'
    api-version:
      description: the full semantic version of the API.
      schema:
        type: string
        example: 1.0.0
    chain-id:
      description: Unique identifier for the request. Also known as the chain id.
      schema:
        type: string
        example: 5EFCCA8940CAEA6B
  examples:
    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'
    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
    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'
    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
    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
    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
    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
  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
  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
      description: 'Basic Authentication - requiring users to input Username: USERNAME-SERIAL and Password as the API key.'
      scheme: basic
    FactSetOAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.factset.com/as/token.oauth2
          scopes: {}
    FactSetApiKey:
      type: http
      scheme: basic
externalDocs:
  description: API Documentation
  url: https://developer.factset.com/api-catalog/factset-fundamentals-api
x-refined-from:
- formula-openapi-original.yml
- fundamentals-openapi-original.yml