API Guide

Adaptive Retrieval offers a single endpoint to retrieve relevant data across any number of S&P datasets using natural language. Data is returned directly from S&P databases, with citations, mitigating risks of LLM hallucinations and giving users an auditability trail to have confidence in responses.

Endpoint

POST https://grounding.kensho.com/api/v2/search

Authentication

The production environment uses S&P Global Okta for authentication. There are two ways to obtain an access token:

Browser Login (Interactive Users)

1. Go to https://grounding.kensho.com/login-spgi (opens in a new tab) and follow the instructions until you reach a page displaying "Logged in as <your email>".
2. Copy the access token displayed on the page. The access token is valid for 1 hour before you need to log in again to renew it.
3. Use the access token as Bearer authentication in your API requests.

Client Credentials (Service Accounts)

For programmatic access, use the OAuth 2.0 client credentials flow with your S&P Global client ID and secret. If you need a service account, reach out to support@kensho.com to be provisioned one.

import requests
 
TOKEN_URL = "https://secure.signin.spglobal.com/oauth2/spglobal/v1/token"
 
def get_access_token(client_id: str, client_secret: str) -> str:
    """Obtain an access token using the client credentials grant."""
    response = requests.post(
        TOKEN_URL,
        data={
            "grant_type": "client_credentials",
            "client_id": client_id,
            "client_secret": client_secret,
            "scope": "api:kensho_grounding",
            "audience": "api://spglobal",
        },
    )
    response.raise_for_status()
    return response.json()["access_token"]
 
 
token = get_access_token("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")

The response will contain an access_token field. Tokens are valid for 1 hour.

Code Examples

import requests
 
url = "https://grounding.kensho.com/api/v2/search"
headers = {
    "Authorization": "Bearer YOUR_TOKEN_HERE",
    "Content-Type": "application/json"
}
data = {
    "query": "What is Apple's P/E ratio?"
}
response = requests.post(url, json=data, headers=headers)
 
print(response.status_code)  # verify this is 200
print(response.json())

Request Parameters

Response Format

The API returns a JSON response with the following structure:

{
    "schema_version": "2.0",
    "response": [...]
}

Schema Version

The schema_version field indicates the version of the response schema being used. The current latest version is "2.0".

Response Data

The response array contains the results of your query. Each item represents a table of data with rich metadata:

{
  "representation_type": "tabular",
  "schema": {
    "fields": [
      {"name": "column1", "type": "string"},
      {"name": "column2", "type": "integer"},
      {"name": "column3", "type": ["number", "null"]}
    ]
  },
  "data": [
    {"column1": "value1", "column2": 42, "column3": 3.14},
    {"column1": "value2", "column2": 84, "column3": null}
  ],
  "sources": [
    {
      "type": "table",
      "source": {
        "uri": "https://example.com/source",
        "name": "Source Name",
        "provider": "S&P Global"
      }
    },
    {
      "type": "cell",
      "row": 0,
      "column": "column1",
      "source": {
        "uri": "https://example.com/specific-source",
        "name": "Specific Cell Source",
        "provider": "S&P Global"
      }
    }
  ],
  "problems": [],
  "metadata": {}
}

Tabular Data Structure

• schema.fields: Array of column definitions with names and types
• data: Array of row objects where each row is a dictionary with column names as keys
• sources: Array of source attributions at table, row, column, or cell level

Source Information

Each source in the sources array provides detailed attribution:

{
  "type": "table|row|column|cell",
  "source": {
    "uri": "https://example.com/source-link",
    "name": "Human-readable source name",
    "provider": "Data provider name"
  },
  "index": 0,
  "name": "col_name",
  "row": 0,
  "column": "col_name"
}

Schema Types

The v2 format uses JSON Schema primitive types for column definitions:

• "null": Null values only
• "boolean": True/false values
• "integer": Whole numbers
• "number": Integers and floating-point numbers
• "string": Text values

Columns can accept multiple types by using an array format:

• ["string", "null"]: String values that can also be null
• ["integer", "number", "null"]: Numeric values that can be null

Problems

Each result has a problems array that contains any actionable issues encountered during data retrieval.

Response Headers

Each API response includes headers to help you monitor your usage:

Error Handling

The API uses standard HTTP status codes along with detailed problem descriptions in the response body.

Authentication Errors

• 401 Unauthorized: Authentication token is missing or invalid. You need to log in again to get a new access token.
• 403 Forbidden: Your token is valid but you don't have permission to access the requested resource.

Access Token Expiration

Access tokens expire after 1 hour. When your token expires, you'll receive a 401 Unauthorized response. To get a new token, visit https://grounding.kensho.com/login-spgi (opens in a new tab) again or use the client credentials flow to obtain a new token programmatically.

Request Errors

• 400 Bad Request: The request was malformed or contained invalid parameters.
• 422 Unprocessable Entity: The request was well-formed but contained semantic errors.

Server Errors

• 500 Internal Server Error: Something went wrong on the server.
• 503 Service Unavailable: The service is temporarily unavailable or overloaded.