components:
  parameters:
    ArchiveID:
      description: Unique identifier for a screen archive to OFDB job
      in: path
      name: id
      required: true
      schema:
        type: string
    PaginationCursor:
      description: Paging index (Initial request may omit)
      in: query
      name: _paginationCursor
      schema:
        type: integer
    PaginationLimit:
      description: Page size limit (minumum 1000, default 10,000, maximum 100,000)
      in: query
      name: _paginationLimit
      schema:
        type: integer
    ScreenCalcID:
      description: Unique identifier for a screen calculation job
      in: path
      name: id
      required: true
      schema:
        type: string
  requestBodies:
    submitArchiveOFDBRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ScreenArchiveOFDBParameters'
      description: Data required for an archive to OFDB request
    submitCalcRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ScreenCalcParameters'
      description: Data required for a calculation request
  responses:
    ActiveJobsResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ActiveJobsData'
      description: ActiveJobsResponse contains id of all of a user's active jobs
    ArchiveOFDBInProgressResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceStatusResponse'
      description: Archive job still in progress
      headers:
        Location:
          description: Relative location to poll for archive status
          schema:
            type: string
        X-FactSet-Api-PickUp-Progress:
          description: Screen archive progress
          schema:
            type: string
    ArchiveOFDBSuccessResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceStatusResponse'
      description: Archive job completed
      headers:
        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
    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
    PaginatedCalculateResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaginatedCalculationResponse'
      description: Paginated Screen Results and Metadata
    Error400InvalidRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorArray'
      description: Invalid request body.
    Error400ScreenOpen:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorArray'
      description: The requested screen could not be opened.
    Error401Response:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorArray'
      description: Invalid or missing authentication.
    Error404Response:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorArray'
      description: Job ID not found.
    Error410Response:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorArray'
      description: The results have been fetched for this ID.
    Error429Response:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorArray'
      description: Too many requests.
      headers:
        X-FactSet-Api-Units-Limit:
          description: Maximum number of jobs.
          schema:
            type: string
        X-FactSet-Api-Units-Remaining:
          description: Number of available jobs.
          schema:
            type: string
    Generic500ErrorResponse:
      description: Internal Server Error
      headers:
        Request-Key:
          description: Provide this key when reporting this issue
          schema:
            type: string
    SubmitArchiveOFDBResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceStatusResponse'
      description: >-
        Successful archive OFDB submission response, returns the job ID unique
        to this archive and the URL in the Location header to check the status
        of the archive.
      headers:
        Location:
          description: Relative location to poll for archive status
          schema:
            type: string
        X-FactSet-Api-Units-Limit:
          description: Maximum number of jobs.
          schema:
            type: string
        X-FactSet-Api-Units-Remaining:
          description: Number of available jobs.
          schema:
            type: string
        RateLimit-Limit:
          description: Number of weekly jobs available.
          schema:
            type: string
        RateLimit-Remaining:
          description: Number of remaining weekly jobs.
          schema:
            type: string
        RateLimit-Reset:
          description: Time, in seconds, until weekly limit resets.
          schema:
            type: string
    SubmitCalculateResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceStatusResponse'
      description: >-
        Successful calculation submission response, returns the job ID unique to
        this calculation and the URL in the Location header to check the status
        of the calculation.
      headers:
        Location:
          description: Relative location to poll for calculation status
          schema:
            type: string
        X-FactSet-Api-Units-Limit:
          description: Maximum number of jobs.
          schema:
            type: string
        X-FactSet-Api-Units-Remaining:
          description: Number of available jobs.
          schema:
            type: string
        RateLimit-Limit:
          description: Number of weekly jobs available.
          schema:
            type: string
        RateLimit-Remaining:
          description: Number of remaining weekly jobs.
          schema:
            type: string
        RateLimit-Reset:
          description: Time, in seconds, until weekly limit resets.
          schema:
            type: string
  schemas:
    ActiveJobsData:
      description: Object containing active jobs ids
      properties:
        data:
          $ref: '#/components/schemas/ActiveJobIDs'
    ActiveJobIDs:
      properties:
        id:
          items:
            type: string
          type: array
      description: Array of active jobs ids associated with the account
      type: object
    ErrorArray:
      description: An array of errors
      properties:
        errors:
          items:
            $ref: '#/components/schemas/ErrorObject'
          type: array
          description: Array of Error Objects
      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
    ErrorObject:
      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
        source:
          $ref: '#/components/schemas/ErrorObjectSource'
        title:
          description: a description of the error
          type: string
      type: object
      description: Associated Error Objects
    ErrorObjectSource:
      properties:
        parameter:
          type: string
      description: >-
        For errors and warnings found in screens, contains the paramID the
        error/warning belongs to
      type: object
    PaginationResponse:
      properties:
        isEstimatedTotal:
          description: Denotes if the 'total' property is an estimation
          type: boolean
        next:
          description: Next cursor to be sent, will be null when there are no more results
          type: string
          nullable: true
        prev:
          description: Previous cursor, currently not supported
          type: integer
          nullable: true
        total:
          description: Total number of rows in the screen
          type: integer
      type: object
    ResourceStatusResponse:
      description: >-
        ResourceStatusResponse contains information regarding the status of a
        calculation job
      properties:
        data:
          properties:
            error:
              $ref: '#/components/schemas/ErrorObject'
            id:
              description: ID of the submitted calculation job
              type: string
            status:
              description: Current status of the calculation job
              type: string
          type: object
      type: object
    ResultsMetadata:
      description: Metadata containing results pagination information
      properties:
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      type: object
    StachPackage:
      description: Stach v2 column oriented paginated screen results
      type: object
    PaginatedCalculationResponse:
      description: Paged results from screen calculation
      properties:
        meta:
          $ref: '#/components/schemas/ResultsMetadata'
        data:
          $ref: '#/components/schemas/StachPackage'
      type: object
    ScreenArchiveOFDBParameters:
      properties:
        data:
          description: Object containing archive request payload
          properties:
            archiveOptions:
              properties:
                archiveDate:
                  description: YYYYMMDD date to archive to
                  type: string
                archiveType:
                  description: >-
                    Type of archive, i.e. ofdbSymbols, ofdbNts, ofdbQuickNts,
                    ofdb
                  type: string
                autoSymbolUpdates:
                  description: Flag to enable automatic symbol updates
                  type: boolean
                existed:
                  description: Indicates that the output file exists
                  type: boolean
                filename:
                  description: OFDB Filename to archive to
                  type: string
                overwriteData:
                  description: >-
                    If true and target file (or date for a time series file)
                    exists, it will be cleared before archiving
                  type: boolean
                quickColumns:
                  description: >-
                    Space delimited list of parameter references to be archived,
                    which are UPPERCASED with the #P. omitted
                  type: string
                symbolType:
                  description: The symbol type for archiving
                  type: string
                timeSeries:
                  description: If true, archive 3D time series OFDB
                  type: boolean
                unsplitHistory:
                  description: Flag indicating split adjust
                  type: boolean
                useReportOrder:
                  description: If true, archive in report order
                  type: boolean
              required:
                - filename
                - archiveType
              type: object
            backtestDate:
              description: >-
                Specifies the backtest date used when running the screen,
                replacing
                  the backtest date saved in the screen, can be written in YYYYMMDD,
                  MM/DD/YYYY or relative (0, -1, 0/-1/0) format.
                Requires addtional access to use.
              type: string
            globalVariablesMap:
              additionalProperties:
                type: string
              description: >-
                Modifies existing global variables for this calculation request,
                temporarily adds them if they do not already exist

                Variable names can only contain the characters A-Z (case
                insensitive). Variable values must be non-empty.
              type: object
            legacyUniverseType:
              description: >-
                Universe type to open legacy screen with. Must be one of
                "equity", "debt", or "fund". Defaults to "equity".
              type: string
            screenName:
              description: File path to a valid screen
              type: string
          required:
            - screenName
          type: object
      required:
        - data
      type: object
    ScreenCalcParameters:
      properties:
        data:
          description: Object containing screen data
          properties:
            backtestDate:
              description: >-
                Specifies the backtest date used when running the screen,
                replacing the backtest date saved in the screen, can be written
                in YYYYMMDD, MM/DD/YYYY or relative (0, -1, 0/-1/0) format.
                Requires addtional access to use.
              type: string
            globalVariablesMap:
              additionalProperties:
                type: string
              description: >-
                Modifies existing global variables for this calculation request,
                temporarily adds them if they do not already exist

                Variable names can only contain the characters A-Z (case
                insensitive). Variable values must be non-empty.
              type: object
            legacyUniverseType:
              description: >-
                Universe type to open legacy screen with. Must be one of
                "equity", "debt", or "fund". Defaults to "equity".
              type: string
            screenName:
              description: File path to a valid screen
              type: string
          required:
            - screenName
          type: object
      required:
        - data
      type: object
  securitySchemes:
    FactSetApiKey:
      type: http
      scheme: basic
info:
  description: >-
    Through the Universal Screening API, you can access the power of FactSet's
    Universal Screening Application.

    Calculate and return the results of your saved Universal Screens.
  title: Factset Universal Screening API
  version: 2.0.2
openapi: 3.0.2
servers:
  - url: https://api.factset.com/universal-screening
security:
  - FactSetApiKey: []
externalDocs:
  description: Read more about STACH 2.0's column organized schema
  url: https://factset.github.io/stachschema/#/v2/ColumnOrganized
paths:
  /v2/job/archive:
    post:
      description: Begins archive of screen to OFDB. Subject to rate limiting by serial.
      operationId: SubmitArchiveOFDB
      requestBody:
        $ref: '#/components/requestBodies/submitArchiveOFDBRequest'
      responses:
        '202':
          $ref: '#/components/responses/SubmitArchiveOFDBResponse'
        '400':
          $ref: '#/components/responses/Error400InvalidRequest'
        '401':
          $ref: '#/components/responses/Error401Response'
        '429':
          $ref: '#/components/responses/Error429Response'
        '500':
          $ref: '#/components/responses/Generic500ErrorResponse'
      tags:
        - Job
  /v2/job/calculate:
    post:
      description: Begins calculation of screen. Subject to rate limiting by serial.
      operationId: SubmitCalculate
      requestBody:
        $ref: '#/components/requestBodies/submitCalcRequest'
      responses:
        '202':
          $ref: '#/components/responses/SubmitCalculateResponse'
        '400':
          $ref: '#/components/responses/Error400InvalidRequest'
        '401':
          $ref: '#/components/responses/Error401Response'
        '429':
          $ref: '#/components/responses/Error429Response'
        '500':
          $ref: '#/components/responses/Generic500ErrorResponse'
      tags:
        - Job
  /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:
        - Job
  /v2/jobs:
    get:
      description: >-
        Retrieve list of all active job ids started by requester's
        username-serial
      operationId: GetAllActiveJobs
      responses:
        '200':
          $ref: '#/components/responses/ActiveJobsResponse'
        '401':
          $ref: '#/components/responses/Error401Response'
        '404':
          $ref: '#/components/responses/Error404Response'
        '500':
          $ref: '#/components/responses/Generic500ErrorResponse'
      tags:
        - Jobs
    delete:
      description: Delete all active jobs started by the requester's username-serial
      operationId: DeleteAllActiveJobs
      responses:
        '204':
          description: No Content
        '401':
          $ref: '#/components/responses/Error401Response'
        '404':
          $ref: '#/components/responses/Error404Response'
        '500':
          $ref: '#/components/responses/Generic500ErrorResponse'
      tags:
        - Jobs
  /v2/job/{id}:
    delete:
      description: Delete a specified job started by the requester's username-serial
      operationId: DeleteActiveJob
      parameters:
        - $ref: '#/components/parameters/ScreenCalcID'
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/Error401Response'
        '404':
          $ref: '#/components/responses/Error404Response'
        '500':
          $ref: '#/components/responses/Generic500ErrorResponse'
      tags:
        - Job
    get:
      description: >-
        Retrieve results of complete screen calculation. Screens with more than
        10,000 rows will be returned in a paginated format. Results may be
        fetched in pages of 1,000 - 100,000 results with 10,000 being the
        default page size.
      operationId: GetCalculateResults
      parameters:
        - $ref: '#/components/parameters/ScreenCalcID'
        - $ref: '#/components/parameters/PaginationLimit'
        - $ref: '#/components/parameters/PaginationCursor'
      responses:
        '200':
          $ref: '#/components/responses/PaginatedCalculateResponse'
        '202':
          $ref: '#/components/responses/CalculateInProgressResponse'
        '400':
          $ref: '#/components/responses/Error400ScreenOpen'
        '401':
          $ref: '#/components/responses/Error401Response'
        '404':
          $ref: '#/components/responses/Error404Response'
        '410':
          $ref: '#/components/responses/Error410Response'
        '500':
          $ref: '#/components/responses/Generic500ErrorResponse'
      tags:
        - Job
tags:
  - name: Job
  - name: Jobs