Factset Status API

openapi: 3.2.0
info:
  title: Factset Status API
  version: '1.0'
  description: 'Operations tagged Status across 3 of this provider''s published API definitions: conversational-api-powered-by-mercury-openapi-original.yml, factset-funds-api-openapi.yml, factset-universal-screening-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.factset.com/conversational/v0
- url: https://api.factset.com/content
  description: Production
- url: https://api.factset.com/universal-screening
tags:
- name: Status
paths:
  /status:
    post:
      operationId: getChatStatus
      summary: Factset Retrieve the status of a chat response process.
      description: 'Returns the status of a chat response for a given chat conversation ID (recevied from the `/create` endpoint). Poll the `/status` endpoint with your conversation ID to confirm when your data is ready.

        Answers may take minutes to generate, depending on the complexity of the query.

        '
      tags:
      - Status
      requestBody:
        description: ID representing the chat process for your query
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatPollingRequest'
            examples:
              Example request:
                $ref: '#/components/examples/ChatPollingRequestExample'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusPollResponse'
              examples:
                Example question:
                  $ref: '#/components/examples/StatusPollResponseCreatedExample'
          headers:
            Location:
              description: Relative URL to the query response.
              schema:
                type: string
                enum:
                - /result
            Api-Supported-Versions:
              description: Comma-separated list of supported major versions.
              schema:
                type: string
              example: '0'
            Api-Version:
              description: Full semantic version of the API.
              schema:
                type: string
              example: 0.1.0
            RateLimit-Limit:
              description: Request limit per second.
              schema:
                type: integer
              example: 10
            RateLimit-Remaining:
              description: Number of available requests.
              schema:
                type: integer
              example: 9
            RateLimit-Reset:
              description: Time remaining (in seconds) until request limit is reset.
              schema:
                type: integer
              example: 1
            X-RateLimit-Limit-minute:
              description: Request limit per minute.
              schema:
                type: integer
              example: 300
            X-RateLimit-Remaining-minute:
              description: Number of available requests in the current minute.
              schema:
                type: integer
              example: 290
            X-DataDirect-Request-Key:
              description: FactSet request ID.
              schema:
                type: string
              example: 65C6BC290A11FB4F
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusPollResponse'
              examples:
                Example question:
                  $ref: '#/components/examples/StatusPollResponseAcceptedExample'
          headers:
            Location:
              description: Relative URL to check the status of the request.
              schema:
                type: string
                enum:
                - /status
            Api-Supported-Versions:
              description: Comma-separated list of supported major versions.
              schema:
                type: string
              example: '0'
            Api-Version:
              description: Full semantic version of the API.
              schema:
                type: string
              example: 0.1.0
            RateLimit-Limit:
              description: Request limit per second.
              schema:
                type: integer
              example: 10
            RateLimit-Remaining:
              description: Number of available requests.
              schema:
                type: integer
              example: 9
            RateLimit-Reset:
              description: Time remaining (in seconds) until request limit is reset.
              schema:
                type: integer
              example: 1
            X-RateLimit-Limit-minute:
              description: Request limit per minute.
              schema:
                type: integer
              example: 300
            X-RateLimit-Remaining-minute:
              description: Number of available requests in the current minute.
              schema:
                type: integer
              example: 290
            X-DataDirect-Request-Key:
              description: FactSet request ID.
              schema:
                type: string
              example: 65C6BC290A11FB4F
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - You are not properly authenticated for use of this API. Please make sure you are logged in to the developer portal or using a valid API key (managed [here](https://developer.factset.com/manage-api-keys)) for access. If you believe you are seeing this message in error, please reach out to your FactSet Support Team representative.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/401UnauthorizedError'
              examples:
                Example error:
                  $ref: '#/components/examples/401UnauthorizedErrorExample'
        '403':
          description: Forbidden - You do not have the entitlements enabled for this service. Please reach out to your FactSet Support Team representative to receive the proper entitlements.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/403ForbiddenError'
              examples:
                Example error:
                  $ref: '#/components/examples/403ForbiddenErrorExample'
        '429':
          description: Too Many Requests - The /status endpoint is currently rate-limited to 10 requests per second for an individual organization. If you are receiving an unexpected amount of these errors, please contact the API team at [genai.offplatform@factset.com](genai.offplatform@factset.com).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceededError'
              examples:
                Example error:
                  $ref: '#/components/examples/RateLimitExceededErrorExample'
          headers:
            RateLimit-Limit:
              description: Request limit per second.
              schema:
                type: integer
              example: 10
            RateLimit-Remaining:
              description: Number of available requests.
              schema:
                type: integer
              example: 9
            RateLimit-Reset:
              description: Time remaining (in seconds) until request limit is reset.
              schema:
                type: integer
              example: 1
            Retry-After:
              description: How long (in seconds) to wait before attempting to send a new request.
              schema:
                type: integer
              example: 1
            X-RateLimit-Limit-minute:
              description: Request limit per minute.
              schema:
                type: integer
              example: 300
            X-RateLimit-Remaining-minute:
              description: Number of available requests in the current minute.
              schema:
                type: integer
              example: 290
            X-DataDirect-Request-Key:
              description: FactSet request ID.
              schema:
                type: string
              example: 65C6BC290A11FB4F
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - FactSetApiKey: []
      - FactSetOAuth2: []
    servers:
    - url: https://api.factset.com/conversational/v0
  /factset-funds/v1/status:
    get:
      tags:
      - Status
      summary: Factset Get Fund's Current Status and Database Availability
      operationId: getStatuses
      description: 'Get the funds active status, share class status, and database availability. Most common use is for coverage checks and id resolution checks.

        '
      parameters:
      - $ref: '#/components/parameters/ids'
      responses:
        '200':
          description: The Statuses response object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/statusesResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '415':
          $ref: '#/components/responses/415'
        '500':
          $ref: '#/components/responses/500'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - BasicAuth: []
    post:
      tags:
      - Status
      summary: Factset Get Fund's Current Status and Database Availability for Large List of Ids.
      description: 'Get the funds active status, share class status, and database availability. Most common use is for coverage checks and id resolution checks.

        '
      operationId: getStatusesForList
      requestBody:
        required: true
        description: The Statuses request body, allowing the user to specify a list of ids.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/statusesRequest'
      responses:
        '200':
          description: The Statuses response object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/statusesResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '415':
          $ref: '#/components/responses/415'
        '500':
          $ref: '#/components/responses/500'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - BasicAuth: []
    servers:
    - url: https://api.factset.com/content
      description: Production
  /v2/job/{id}/status:
    get:
      description: Polls the job with a given screen ID and returns job status
      operationId: PollCalculate
      parameters:
      - $ref: '#/components/parameters/ScreenCalcID'
      responses:
        '201':
          $ref: '#/components/responses/CalculateSuccessResponse'
        '202':
          $ref: '#/components/responses/CalculateInProgressResponse'
        '401':
          $ref: '#/components/responses/Error401Response'
        '404':
          $ref: '#/components/responses/Error404Response'
        '410':
          $ref: '#/components/responses/Error410Response'
        '500':
          $ref: '#/components/responses/Generic500ErrorResponse'
      tags:
      - Status
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - FactSetApiKey: []
    servers:
    - url: https://api.factset.com/universal-screening
components:
  schemas:
    ErrorObject:
      description: Represents a single error, with error name and identifiers
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        code:
          type: string
    RateLimitExceededError:
      description: Error response when rate limit has been exceeded.
      type: object
      properties:
        message:
          type: string
          enum:
          - API rate limit exceeded
    403ForbiddenError:
      description: Error response for a user without entitlements to the API.
      type: string
    401UnauthorizedError:
      description: Error response for a user without authentication to use the API.
      type: string
    ChatPollingRequest:
      description: Request body containing the chat conversation ID
      type: object
      properties:
        data:
          type: object
          properties:
            conversationId:
              type: string
              format: uuid
    Error:
      description: Wrapper containing metadata and appropriate errors as thrown by the API
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
    StatusPollResponse:
      description: Response from `/status` containing the chat ID and status of chat processing
      type: object
      properties:
        data:
          type: object
          properties:
            conversationId:
              type: string
              format: uuid
            status:
              type: string
              enum:
              - executing
              - created
    errorResponse:
      type: object
      title: Error Response
      properties:
        status:
          description: status
          type: string
          example: Bad Request
        timestamp:
          description: timestamp in YYYY-MM-DD HH:MM:SS.SSS
          type: string
          example: '2019-11-01 11:09:41.918'
          format: date-time
        path:
          description: The Endpoint path {package}/version/{endpoint}
          type: string
          example: /factset-funds/v1/superRegion
        message:
          description: The plain text error message
          type: string
          example: Validation Error
        subErrors:
          description: subErrors related to the error message. Null if not applicable.
          type: object
          properties:
            object:
              description: the operation ID
              type: string
            field:
              description: Parameter Field Name
              type: string
            message:
              description: Error message
              type: string
            rejectedValue:
              description: Rejected Values in an Array
              type: array
              items:
                type: string
          example: example_value
    ids:
      type: array
      items:
        type: string
      minItems: 1
      maxItems: 1000
      description: 'The requested Fund Identifier. FactSet Identifiers, tickers, CUSIP and SEDOL are accepted input. <p>***ids limit** =  1000 per request*</p> *<p>Make note, GET Method URL request lines are also limited to a total length of 8192 bytes (8KB). In cases where the service allows for thousands of ids, which may lead to exceeding this request line limit of 8KB, its advised for any requests with large request lines to be requested through the respective "POST" method.</p>*

        '
      example:
      - MABAX
      - FCNTX
    statuses:
      title: Statuses Object
      type: object
      properties:
        fsymId:
          description: FactSet Security Identifier. Six alpha-numeric characters, excluding vowels, with a -S suffix (XXXXXX-S), resolved from the requestId of the Fund requested.
          type:
          - string
          - 'null'
          example: FNK7XP-S
          x-fds-fql-formula: FSYM_SECURITY_PERM_ID('SECURITY')
        activeFlag:
          description: Binary flag to indicate whether the fund is currently active, where 1 is active and 0 is inactive.
          type:
          - integer
          - 'null'
          example: 1
          x-fds-fql-formula: FFD_ACTIVE
        shrClassActiveFlag:
          description: Returns a binary indicator of whether the specified share class is currently active, where 1 is active and 0 is inactive.
          type:
          - integer
          - 'null'
          example: 1
          x-fds-fql-formula: FFD_SHR_CLS_ACTIVE
        isonFFD:
          description: Returns a binary indicator of whether the specified fund is available in the FactSet Funds Database (FFD).
          type:
          - integer
          - 'null'
          example: 1
          x-fds-fql-formula: ISON_FFD
        requestId:
          description: The requested Id sent as input.
          type: string
          example: MABAX
    statusesResponse:
      type: object
      title: Statuses Response
      properties:
        data:
          description: Array of Statuses Objects
          type: array
          items:
            $ref: '#/components/schemas/statuses'
          example: []
    statusesRequest:
      title: Statuses Request Body
      description: Classifications Request Body
      type: object
      properties:
        ids:
          $ref: '#/components/schemas/ids'
      required:
      - ids
    ErrorObject_2:
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        id:
          description: A unique ID for the occurrence of the error. It is advised to log this code and include it if you contact FactSet support desk.
          type: string
          example: abc123
        source:
          $ref: '#/components/schemas/ErrorObjectSource'
        title:
          description: a description of the error
          type: string
          example: Example Title
      type: object
      description: Associated Error Objects
    ErrorArray:
      description: An array of errors
      properties:
        errors:
          items:
            $ref: '#/components/schemas/ErrorObject_2'
          type: array
          description: Array of Error Objects
          example: []
      type: object
    ErrorCode:
      description: Factset API specific error codes
      enum:
      - notAuthenticated
      - notAuthorized
      - notFound
      - endpointNotFound
      - parameterError
      - genericServerError
      - resourceGone
      - quantityLimitsExceeded
      - universal_screening_parameterError
      - universal_screening_parameterWarning
      type: string
    ResourceStatusResponse:
      description: ResourceStatusResponse contains information regarding the status of a calculation job
      properties:
        data:
          properties:
            error:
              $ref: '#/components/schemas/ErrorObject_2'
            id:
              description: ID of the submitted calculation job
              type: string
            status:
              description: Current status of the calculation job
              type: string
          type: object
          example: example_value
      type: object
    ErrorObjectSource:
      properties:
        parameter:
          type: string
          example: example_value
      description: For errors and warnings found in screens, contains the paramID the error/warning belongs to
      type: object
  examples:
    403ForbiddenErrorExample:
      value: 'Client does not have the required CACCESS: {00QAI}, Request key: 65CA96B3129489A6'
    RateLimitExceededErrorExample:
      value:
        message: API rate limit exceeded
    401UnauthorizedErrorExample:
      value: Authentication Failed
    ChatPollingRequestExample:
      value:
        data:
          conversationId: 9c1031c2-5463-47ae-81b3-126a68f0c2a6
    StatusPollResponseAcceptedExample:
      value:
        data:
          conversationId: 9c1031c2-5463-47ae-81b3-126a68f0c2a6
          status: executing
    StatusPollResponseCreatedExample:
      value:
        data:
          conversationId: 9c1031c2-5463-47ae-81b3-126a68f0c2a6
          status: created
    unsupportedMediaType:
      summary: Unsupported Media Type
      description: This bad request occurs when the media type passed in the request is not supported. Currently the APIs only support 'application/json'.
      value:
        status: Unsupported Media Type
        timestamp: '2019-11-05 09:42:27.237'
        path: /factset-funds/v1/{endpoint}
        message: text/html media type is not supported. Supported media types are application/json
        subErrors: null
    badRequestDateFormat:
      summary: Bad Request - Date Format
      description: This bad request occurs when a request doesn't use the YYYY-MM-DD in the date parameters. To resolve, convert your date to YYYY-MM-DD.
      value:
        status: Bad Request
        timestamp: '2019-10-31 16:08:07.945'
        path: /factset-funds/v1/{endpoint}
        message: 'The date parameter ''startDate'' must be in the following date format: YYYY-MM-DD'
        subErrors: null
    badRequestMalformedJSON:
      summary: Bad Request - Malformed JSON Request
      description: This error may be returned when the request body is specified as JSON, but is not in proper JSON format.
      value:
        status: Bad Request
        timestamp: '2019-11-05 09:48:29.18'
        path: /factset-funds/v1/{endpoint}
        message: Malformed JSON Request
        subErrors: null
    badRequestInvalidParameters:
      summary: Bad Request - Invalid Parameters
      description: This error message occurs when a request parameter is used in which is not recognized by the service. Please revise your request to include only the parameters listed in the specification. Typical causes are spelling mistakes and use of improper casing.
      value:
        status: Bad Request
        timestamp: '2020-06-12 15:58:54.068'
        path: /factset-funds/v1/{endpoint}
        message: 'Invalid Parameter (s): fakeParameterName1 fakeParameterName2. Please modify your request to use parameters outlined in the specification for this endpoint.'
        subErrors: null
    badRequestFutureDate:
      summary: Bad Request - Future Date
      description: This error message occurs when a future date is requested in the startDate and endDate parameters. Please revise your request to include dates as of today's current date or any prior historical date.
      value:
        status: Bad Request
        timestamp: '2020-06-12 15:52:48.091'
        path: /factset-funds/v1/{endpoint}
        message: The use of future dates is not applicable in this endpoint. Please revise your request to include dates up to today's current date.
        subErrors: null
    forbidden:
      summary: Forbidden
      description: The USERNAME-SERIAL attempted to request the endpoint is not authorized to access. The request was a legal request, but the server is refusing to respond. Please reach out to FactSet Account Team for assistance with authorization.
      value:
        status: Forbidden
        timestamp: '2020-06-12 16:08:51.731'
        path: /factset-funds/v1/{endpoint}
        message: USERNAME-SERIAL does not have permission to use /factset-funds /v1/{endpoint}
        subErrors: null
    generalException:
      summary: Internal Server Error - General Exception
      description: This is the most general error that can be returned to by the service. Please `Report Issue` to FactSet.
      value:
        status: Internal Server Error
        timestamp: '2019-11-01 10:36:01.944'
        path: /factset-funds/v1/{endpoint}
        message: Unexpected error
        subErrors: null
    notWritable:
      summary: Internal Server Error - Not Writable
      description: This error may be returned when the server encounters an error writing the JSON response.
      value:
        status: Internal Server Error
        timestamp: '2019-11-05 09:48:29.18'
        path: /factset-funds/v1/{endpoint}
        message: Error writing JSON output
        subErrors: null
    unauthenticated:
      summary: User Authentication Failed
      description: This occurs when a user is not properly authenticated or recognized by the service. Please double check the USERNAME-SERIAL and API-Key used to request and ensure you are within the IP range specified for the Key. Report Issue under 401 error for help with troubleshooting.
      value:
        status: User Authentication Failed
        timestamp: '2019-10-31 16:08:07.945'
        path: /factset-funds/v1/{endpoint}
        message: User Authentication Failed.
        subErrors: null
    badRequestRequiredParameter:
      summary: Bad Request - Required Parameter Missing
      description: This error message occurs when the request does not include the required parameters. Required parameters are indicated with a red asterisks symbol in the specification file.
      value:
        status: Bad Request
        timestamp: '2020-06-12 15:48:42.016'
        path: /factset-funds/v1/{endpoint}
        message: The parameter 'ids' is required and may not be empty.
        subErrors: null
    badRequestReadTimeout:
      summary: Bad Request - Read Timeout
      description: This error may be returned if it takes more than 29 seconds to hear back from the data fetch service.
      value:
        status: Bad Request
        timestamp: '2019-11-04 16:18:38.949'
        path: /factset-funds/v1/{endpoint}
        message: The request took too long. Try again with a smaller request.
        subErrors: null
  responses:
    '403':
      description: The USERNAME-SERIAL attempted to request the endpoint is not authorized to access. The request was a legal request, but the server is refusing to respond. Please reach out to FactSet Account Team for assistance with authorization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/forbidden'
    '400':
      description: Bad Request. This can occur for several reasons. Please review the "message" for more details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/badRequestDateFormat'
            Bad Request - Missing Required Parameter:
              $ref: '#/components/examples/badRequestRequiredParameter'
            Bad Request - Future Date:
              $ref: '#/components/examples/badRequestFutureDate'
            Bad Request - Invalid Parameter:
              $ref: '#/components/examples/badRequestInvalidParameters'
            Bad Request - Malformed JSON:
              $ref: '#/components/examples/badRequestMalformedJSON'
            Bad Request - Read Timeout:
              $ref: '#/components/examples/badRequestReadTimeout'
    '415':
      description: Unsupported Media Type. This error may be returned when the caller sends a resource in a format that is not accepted by the server. This can be fixed by ensuring that Content-Type header is set to the correct value. In this instance, "application/json" would be the appropriate value.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/unsupportedMediaType'
    '401':
      description: Unauthenticated USERNAME-SERIAL. Ensure you are logged in and have successfully generated an API KEY for the IP range you are connecting from. For more help, select the **Report Issue** in the top right corner of this Developer Portal specification card and choose Connectivity 401 or 403 Responses.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/unauthenticated'
    '500':
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Internal Server Error - Not Writable:
              $ref: '#/components/examples/notWritable'
            Internal Server Error - General Exception:
              $ref: '#/components/examples/generalException'
    Error410Response:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorArray'
      description: The results have been fetched for this ID.
    CalculateSuccessResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceStatusResponse'
      description: Job completed
      headers:
        Location:
          description: Relative location to pick up screen results, calculate route only
          schema:
            type: string
        X-FactSet-Api-PickUp-Progress:
          description: Screen progress
          schema:
            type: string
    CalculateInProgressResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceStatusResponse'
      description: Calculation job still in progress
      headers:
        Location:
          description: Relative location to poll for status
          schema:
            type: string
        X-FactSet-Api-PickUp-Progress:
          description: Screen progress
          schema:
            type: string
    Generic500ErrorResponse:
      description: Internal Server Error
      headers:
        Request-Key:
          description: Provide this key when reporting this issue
          schema:
            type: string
    Error404Response:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorArray'
      description: Job ID not found.
    Error401Response:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorArray'
      description: Invalid or missing authentication.
  parameters:
    ids:
      name: ids
      in: query
      schema:
        type: array
        items:
          type: string
        minItems: 1
        maxItems: 1000
      required: true
      explode: false
      description: 'The requested fund identifier. FactSet Identifiers, tickers, CUSIP, SEDOL, and ISIN are accepted inputs. <p>***ids limit** =  1000 per request*</p> *<p>Make note, GET Method URL request lines are also limited to a total length of 8192 bytes (8KB). In cases where the service allows for thousands of ids, which may lead to exceeding this request line limit of 8KB, its advised for any requests with large request lines to be requested through the respective "POST" method.</p>*

        '
      examples:
        oneId:
          summary: One Market Identifier
          value:
          - MABAX-US
        multipleIds:
          summary: Multiple Market Identifiers
          value:
          - MABAX-US
          - FCNTX-US
    ScreenCalcID:
      description: Unique identifier for a screen calculation job
      in: path
      name: id
      required: true
      schema:
        type: string
  securitySchemes:
    FactSetOAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.factset.com/as/token.oauth2
          scopes: {}
    FactSetApiKey:
      type: http
      scheme: basic
    BasicAuth:
      type: http
      scheme: basic
x-refined-from:
- conversational-api-powered-by-mercury-openapi-original.yml
- factset-funds-api-openapi.yml
- factset-universal-screening-api-openapi.yml