Downloading data for a universe asynchronously

Overview

The Universe APIs or Asynchronous APIs are designed for clients looking to retrieve information for the whole Clarity AI's universe OR for a list of specific ISINs and/or metrics/scores. Requests to these endpoints create an async job to return the requested data.

In general, the flow requires four steps:

1. Make a POST request to an endpoint
2. Retrieve the jobId or uuid that is provided in the response
3. Check the status of the job using the Async Job - Get job status endpoint
4. Download the data either using the Async Job - Download result file or Async Job - Download compressed result file endpoints

Example

Make the request

In this example, we will use the ESG Risk module to retrieve a set of scores for a set of organizations. Other Universe API endpoints work in a similar way.

To request the data, a POST call to Async Job - Request ESG Risk Organizations Scores is needed, with the following information:

1. scoreIds specifies which scores are being requested
2. permIds specifies which organizations the information is needed for
3. scoringProfileId Optional parameter which can be used to specify a custom ESG Risk custom scoring profile.

Sample request

{
  "scoreIds": [
    "ENVIRONMENTAL",
    "SOCIAL",
    "GOVERNANCE",
    "ESG"
  ],
  "permIds": [
		"4295890594",
		"4298459348",
		"4295903076"
  ],
  "scoringProfileId": "ESG_RISK_INDUSTRY_CONSENSUS"
}

Sample response

{
  "uuid": "644381ce-93c5-4a6b-b0a7-32a5a62d4acb"
}

Check the status

To check the status of the job using Async Job - Get job status endpoint, provide the jobId parameter.

{
  "statusMessage": "SUCCESS"
}

Download the file

To download the data in a CSV format use Async Job - Download result file, provide the jobId parameter.

It is recommended to use the Async Job - Download compressed result file endpoint for jobs related to requests at the universe level. This will return a gzip compressed version of the CSV file.