Factset Result API

openapi: 3.2.0
info:
  title: Factset Conversational API Powered by FactSet Mercury Result API
  description: 'The FactSet Conversational API allows clients to white-label core FactSet Mercury capabilities in a client’s chatbot experience.


    Request data from FactSet using a single natural language query. Start the response generation using the `/create` endpoint, poll the status using `/status`. Once the result is ready, retrieve it using `/result`.


    **Please note:** "Natural language" in this documentation refers to modern conversational English. Support for other languages is currently unavailable.

    '
  version: 0.1.0
  license:
    name: Apache License, Version 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  contact:
    name: FactSet Research Systems
    email: api@factset.com
    url: https://developer.factset.com/contact
servers:
- url: https://api.factset.com/conversational/v0
security:
- FactSetApiKey: []
- FactSetOAuth2: []
tags:
- name: Result
paths:
  /result:
    post:
      operationId: getChatResult
      summary: Factset Retrieve the completed response for your query.
      description: 'Returns FactSet content and data in response to the query provided to the `/create` endpoint. This endpoint is the final step in the single-question request process.

        Responses contain a combination of Microsoft Adaptive Cards for data/tables and markdown for text.

        '
      tags:
      - Result
      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:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
              examples:
                Example question:
                  $ref: '#/components/examples/QueryResponseExample'
          headers:
            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 /result 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'
components:
  schemas:
    OpenActiveGraph:
      type: object
      properties:
        action:
          type: string
          enum:
          - OpenActiveGraph
        label:
          type: string
        xml:
          type: string
    ChatPollingRequest:
      description: Request body containing the chat conversation ID
      type: object
      properties:
        data:
          type: object
          properties:
            conversationId:
              type: string
              format: uuid
    FederationData:
      description: Data surfaced by processing the query through FactSet Mercury. Contains financial data, if accessible and available, as well as natural language answer to the query
      type: object
      properties:
        type:
          description: 'Data type contained in the FederationData value.

            '
          type:
          - string
          - 'null'
          enum:
          - string
          - AdaptiveCard
          - NextStep
        value:
          $ref: '#/components/schemas/FederationDataValue'
    QueryResponse:
      description: Query response body containing data from FactSet's Mercury LLM and metadata describing the model interaction
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              format: uuid
            data:
              type: array
              items:
                $ref: '#/components/schemas/FederationData'
      required:
      - data
    OpenComponent:
      type: object
      properties:
        action:
          type: string
          enum:
          - OpenComponent
        name:
          type: string
        label:
          type: string
        category:
          type: string
        parameters:
          type: object
        report:
          type: object
          properties:
            fdsup:
              type: string
            http:
              type: string
    AdaptiveCard:
      description: 'AdaptiveCard: Microsoft Adaptive Card containing response data surfaced from FactSet content sets. `Value` property of parent FederationData contains a JSON serialized presentation of a Microsoft Adaptive Card. See [Microsoft docs](https://learn.microsoft.com/en-us/adaptive-cards/) for Adaptive Card documentation, and the [Adaptive Card schema explorer](https://adaptivecards.io/explorer/) for schema details.

        '
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
            version:
              type: string
          required:
          - type
          - version
          additionalProperties: true
    NextStep:
      description: 'NextStep: A serialized list of `action` items, which are directives to a front-end application to perform a certain task i.e. open a FactSet application or component, download an Excel file.

        '
      type: array
      items:
        anyOf:
        - $ref: '#/components/schemas/OpenComponent'
        - $ref: '#/components/schemas/OpenUrl'
        - $ref: '#/components/schemas/OpenActiveGraph'
    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
    401UnauthorizedError:
      description: Error response for a user without authentication to use the API.
      type: string
    String:
      description: 'String: Chat response to the query. Provides an answer to the question or references further attached data. `Value` property of parent FederationData contains a string with natural language.

        '
      type: string
    Error:
      description: Wrapper containing metadata and appropriate errors as thrown by the API
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
    OpenUrl:
      type: object
      properties:
        action:
          type: string
          enum:
          - OpenUrl
        label:
          type: string
        category:
          type: string
        url:
          type: object
          properties:
            fdsup:
              type: string
            http:
              type: string
    403ForbiddenError:
      description: Error response for a user without entitlements to the API.
      type: string
    FederationDataValue:
      oneOf:
      - $ref: '#/components/schemas/String'
      - $ref: '#/components/schemas/AdaptiveCard'
      - $ref: '#/components/schemas/NextStep'
  examples:
    QueryResponseExample:
      value:
        data:
          id: 9c1031c2-5463-47ae-81b3-126a68f0c2a6
          data:
          - type: string
            value: These banks are ranked to compare the percentage of commercial real estate (CRE) loans to their total loan portfolios to show which have the least exposure to the downturn in commercial occupancy rates.
          - type: AdaptiveCard
            value:
              type: AdaptiveCard
              version: '1.3'
              body:
              - type: TextBlock
                size: large
                weight: lighter
                text: Tesla, Inc. (TSLA-US)
              - type: ColumnSet
                columns:
                - type: Column
                  width: auto
                  items:
                  - type: TextBlock
                    size: extraLarge
                    text: $619.4 B
                  verticalContentAlignment: bottom
                  spacing: extraLarge
                - type: Column
                  width: auto
                  items:
                  - type: TextBlock
                    size: medium
                    color: light
                    text: Enterprise Value
                  verticalContentAlignment: bottom
                  spacing: extraLarge
              - type: Image
                url: data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI0MDAiIGhlaWdodD0iMTgwIiB2aWV3Qm94PSIwIDAgNDAwIDE4MCI+PHN2ZyB3aWR0aD0iNDAwIiBoZWlnaHQ9IjE4MCIgdmlld0JveD0iMCAwIDQwMCAxODAiIHN0eWxlPSJwb3NpdGlvbjogYWJzb2x1dGU7IHBvaW50ZXItZXZlbnRzOiBub25lOyBsZWZ0OiAwcHg7IHRvcDogMHB4OyI+PGRlZnM+PGNsaXBQYXRoIGlkPSJDTElQMCI+PHBhdGggZD0iTSA1IDExIEwgMzUyIDExIEwgMzUyIDE1MiBMIDUgMTUyIFoiLz48L2NsaXBQYXRoPjxjbGlwUGF0aCBpZD0iQ0xJUDEiPjxwYXRoIGQ9Ik0gNSAxMSBMIDM1MiAxMSBMIDM1MiAxNTIgTCA1IDE1MiBaIi8+PC9jbGlwUGF0aD48L2RlZnM+PGcgbGluZS1taXRlcj0iNCIgc3R5bGU9InRyYW5zZm9ybTogc2NhbGUoMSwgMSk7Ij48ZyBvcGFjaXR5PSIwLjIiPjxwYXRoIGQ9Ik0gNS41IDE1MiBMIDUuNSAxMSBNIDg3LjUgMTUyIEwgODcuNSAxMSBNIDE2OS41IDE1MiBMIDE2OS41IDExIE0gMjUwLjUgMTUyIEwgMjUwLjUgMTEgTSAzMzIuNSAxNTIgTCAzMzIuNSAxMSBNIDUgMTUyLjUgTCAzNTIgMTUyLjUgTSA1IDEzMi41IEwgMzUyIDEzMi41IE0gNSAxMTIuNSBMIDM1MiAxMTIuNSBNIDUgOTIuNSBMIDM1MiA5Mi41IE0gNSA3MS41IEwgMzUyIDcxLjUgTSA1IDUxLjUgTCAzNTIgNTEuNSBNIDUgMzEuNSBMIDM1MiAzMS41IE0gNSAxMS41IEwgMzUyIDExLjUiIGZpbGw9Im5vbmUiIHNoYXBlLXJlbmRlcmluZz0iY3Jpc3BFZGdlcyIgc3Ryb2tlPSJyZ2IoMTA5LDExNywxMzYpIiBzdHJva2Utd2lkdGg9IjEiLz48cGF0aCBkPSJNIDUgMTUyLjUgTCAzNTIgMTUyLjUiIGZpbGw9Im5vbmUiIHN0cm9rZT0icmdiKDUxLDYzLDc2KSIgc3Ryb2tlLXdpZHRoPSIxIi8+PHBhdGggZD0iTSA1LjUgMTYxIEwgNS41IDE1MiBNIDg3LjUgMTYxIEwgODcuNSAxNTIgTSAxNjkuNSAxNjEgTCAxNjkuNSAxNTIgTSAyNTAuNSAxNjEgTCAyNTAuNSAxNTIgTSAzMzIuNSAxNjEgTCAzMzIuNSAxNTIgTSA1LjUgMTU3IEwgNS41IDE1MiBNIDI1LjUgMTU3IEwgMjUuNSAxNTIgTSA0Ni41IDE1NyBMIDQ2LjUgMTUyIE0gNjYuNSAxNTcgTCA2Ni41IDE1MiBNIDg3LjUgMTU3IEwgODcuNSAxNTIgTSAxMDcuNSAxNTcgTCAxMDcuNSAxNTIgTSAxMjcuNSAxNTcgTCAxMjcuNSAxNTIgTSAxNDguNSAxNTcgTCAxNDguNSAxNTIgTSAxNjkuNSAxNTcgTCAxNjkuNSAxNTIgTSAxODkuNSAxNTcgTCAxODkuNSAxNTIgTSAyMDkuNSAxNTcgTCAyMDkuNSAxNTIgTSAyMzAuNSAxNTcgTCAyMzAuNSAxNTIgTSAyNTAuNSAxNTcgTCAyNTAuNSAxNTIgTSAyNzEuNSAxNTcgTCAyNzEuNSAxNTIgTSAyOTEuNSAxNTcgTCAyOTEuNSAxNTIgTSAzMTEuNSAxNTcgTCAzMTEuNSAxNTIgTSAzMzIuNSAxNTcgTCAzMzIuNSAxNTIgTSAzNTIuNSAxNTcgTCAzNTIuNSAxNTIiIGZpbGw9Im5vbmUiIHNoYXBlLXJlbmRlcmluZz0iY3Jpc3BFZGdlcyIgc3Ryb2tlPSJyZ2IoMTA5LDExNywxMzYpIiBzdHJva2Utd2lkdGg9IjEiLz48cGF0aCBkPSJNIDM1Mi41IDE1MiBMIDM1Mi41IDExIiBmaWxsPSJub25lIiBzdHJva2U9InJnYig1MSw2Myw3NikiIHN0cm9rZS13aWR0aD0iMSIvPjxwYXRoIGQ9Ik0gMzUyIDE1Mi41IEwgMzYxIDE1Mi41IE0gMzUyIDEzMi41IEwgMzYxIDEzMi41IE0gMzUyIDExMi41IEwgMzYxIDExMi41IE0gMzUyIDkyLjUgTCAzNjEgOTIuNSBNIDM1MiA3MS41IEwgMzYxIDcxLjUgTSAzNTIgNTEuNSBMIDM2MSA1MS41IE0gMzUyIDMxLjUgTCAzNjEgMzEuNSBNIDM1MiAxMS41IEwgMzYxIDExLjUiIGZpbGw9Im5vbmUiIHNoYXBlLXJlbmRlcmluZz0iY3Jpc3BFZGdlcyIgc3Ryb2tlPSJyZ2IoMTA5LDExNywxMzYpIiBzdHJva2Utd2lkdGg9IjEiLz48L2c+PHRleHQgeD0iMzkiIHk9IjE3My41IiBmaWxsPSJyZ2IoOTYsMTEyLDEyMykiIGZvbnQtZmFtaWx5PSImcXVvdDtXb3JrIFNhbnMmcXVvdDssIHNhbnMtc2VyaWYiIGZvbnQtc2l6ZT0iMTAiPicyMDwvdGV4dD48dGV4dCB4PSIxMjIiIHk9IjE3My41IiBmaWxsPSJyZ2IoOTYsMTEyLDEyMykiIGZvbnQtZmFtaWx5PSImcXVvdDtXb3JrIFNhbnMmcXVvdDssIHNhbnMtc2VyaWYiIGZvbnQtc2l6ZT0iMTAiPicyMTwvdGV4dD48dGV4dCB4PSIyMDIuNSIgeT0iMTczLjUiIGZpbGw9InJnYig5NiwxMTIsMTIzKSIgZm9udC1mYW1pbHk9IiZxdW90O1dvcmsgU2FucyZxdW90Oywgc2Fucy1zZXJpZiIgZm9udC1zaXplPSIxMCI+JzIyPC90ZXh0Pjx0ZXh0IHg9IjI4My41IiB5PSIxNzMuNSIgZmlsbD0icmdiKDk2LDExMiwxMjMpIiBmb250LWZhbWlseT0iJnF1b3Q7V29yayBTYW5zJnF1b3Q7LCBzYW5zLXNlcmlmIiBmb250LXNpemU9IjEwIj4nMjM8L3RleHQ+PHRleHQgeD0iMzgzLjUiIHk9IjE1NS41IiBmaWxsPSJyZ2IoOTYsMTEyLDEyMykiIGZvbnQtZmFtaWx5PSImcXVvdDtXb3JrIFNhbnMmcXVvdDssIHNhbnMtc2VyaWYiIGZvbnQtc2l6ZT0iMTAiPjA8L3RleHQ+PHRleHQgeD0iMzcxLjUiIHk9IjEzNC41IiBmaWxsPSJyZ2IoOTYsMTEyLDEyMykiIGZvbnQtZmFtaWx5PSImcXVvdDtXb3JrIFNhbnMmcXVvdDssIHNhbnMtc2VyaWYiIGZvbnQtc2l6ZT0iMTAiPjIwMDwvdGV4dD48dGV4dCB4PSIzNzEuNSIgeT0iMTE0LjUiIGZpbGw9InJnYig5NiwxMTIsMTIzKSIgZm9udC1mYW1pbHk9IiZxdW90O1dvcmsgU2FucyZxdW90Oywgc2Fucy1zZXJpZiIgZm9udC1zaXplPSIxMCI+NDAwPC90ZXh0Pjx0ZXh0IHg9IjM3MS41IiB5PSI5NC41IiBmaWxsPSJyZ2IoOTYsMTEyLDEyMykiIGZvbnQtZmFtaWx5PSImcXVvdDtXb3JrIFNhbnMmcXVvdDssIHNhbnMtc2VyaWYiIGZvbnQtc2l6ZT0iMTAiPjYwMDwvdGV4dD48dGV4dCB4PSIzNzEuNSIgeT0iNzQuNSIgZmlsbD0icmdiKDk2LDExMiwxMjMpIiBmb250LWZhbWlseT0iJnF1b3Q7V29yayBTYW5zJnF1b3Q7LCBzYW5zLXNlcmlmIiBmb250LXNpemU9IjEwIj44MDA8L3RleHQ+PHRleHQgeD0iMzY1LjUiIHk9IjU0LjUiIGZpbGw9InJnYig5NiwxMTIsMTIzKSIgZm9udC1mYW1pbHk9IiZxdW90O1dvcmsgU2FucyZxdW90Oywgc2Fucy1zZXJpZiIgZm9udC1zaXplPSIxMCI+MSwwMDA8L3RleHQ+PHRleHQgeD0iMzY1LjUiIHk9IjM0LjUiIGZpbGw9InJnYig5NiwxMTIsMTIzKSIgZm9udC1mYW1pbHk9IiZxdW90O1dvcmsgU2FucyZxdW90Oywgc2Fucy1zZXJpZiIgZm9udC1zaXplPSIxMCI+MSwyMDA8L3RleHQ+PHRleHQgeD0iMzY0LjUiIHk9IjE0LjUiIGZpbGw9InJnYig5NiwxMTIsMTIzKSIgZm9udC1mYW1pbHk9IiZxdW90O1dvcmsgU2FucyZxdW90Oywgc2Fucy1zZXJpZiIgZm9udC1zaXplPSIxMCI+MSw0MDA8L3RleHQ+PGcgY2xpcC1wYXRoPSJ1cmwoI0NMSVAxKSI+PGcgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNSwgMTEpIj48cGF0aCBkPSJNIDEwIDEyOCBMIDMwIDExNSBMIDUxIDg5IEwgNzEgNTYgTCA5MiA2MiBMIDExMiA2MCBMIDEzMiA0OSBMIDE1MyAxNCBMIDE3MyAxMiBMIDE5NCA2MSBMIDIxNCA0MSBMIDIzNSA5OSBMIDI1NSA2OCBMIDI3NSA0OCBMIDI5NiA1MiBMIDMxNiA1MyBMIDMzNiA3OCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJyZ2IoMzMsMTQ4LDI1NSkiIHN0cm9rZS13aWR0aD0iMiIvPjwvZz48L2c+PC9nPjwvc3ZnPjxzdmcgd2lkdGg9IjQwMCIgaGVpZ2h0PSIxODAiIHZpZXdCb3g9IjAgMCA0MDAgMTgwIiBzdHlsZT0icG9zaXRpb246IGFic29sdXRlOyBwb2ludGVyLWV2ZW50czogbm9uZTsgbGVmdDogMHB4OyB0b3A6IDBweDsiLz48c3ZnIHdpZHRoPSI0MDAiIGhlaWdodD0iMTgwIiB2aWV3Qm94PSIwIDAgNDAwIDE4MCIgc3R5bGU9InBvc2l0aW9uOiBhYnNvbHV0ZTsgcG9pbnRlci1ldmVudHM6IG5vbmU7IGxlZnQ6IDBweDsgdG9wOiAwcHg7Ii8+PHN2ZyB3aWR0aD0iNDAwIiBoZWlnaHQ9IjE4MCIgdmlld0JveD0iMCAwIDQwMCAxODAiIHN0eWxlPSJwb3NpdGlvbjogYWJzb2x1dGU7IHBvaW50ZXItZXZlbnRzOiBub25lOyBsZWZ0OiAwcHg7IHRvcDogMHB4OyIvPjwvc3ZnPg==
              - type: TextBlock
                size: small
                color: light
                isSubtle: true
                text: As of 06 Feb 2024
          - type: NextStep
            value:
            - action: OpenComponent
              name: fusion component name
              label: View All 50 Banks by CRE % of Total Loans
              category: Company/Security
              parameters:
                key1: value1
                key2: value2
              report:
                fdsup: fdsup://...
                http: http://...
            - action: OpenActiveGraph
              label: Download as Active Graph
              xml: <XML to output an Excel file>
            - action: OpenUrl
              label: Screen for Similar Companies
              category: Screening
              url:
                fdsup: fdsup://...
                http: http://...
    403ForbiddenErrorExample:
      value: 'Client does not have the required CACCESS: {00QAI}, Request key: 65CA96B3129489A6'
    RateLimitExceededErrorExample:
      value:
        message: API rate limit exceeded
    ChatPollingRequestExample:
      value:
        data:
          conversationId: 9c1031c2-5463-47ae-81b3-126a68f0c2a6
    401UnauthorizedErrorExample:
      value: Authentication Failed
  securitySchemes:
    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/conversational-api-powered-factset-mercury