API Guide

Kensho Grounding Agent 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-alpha.preview.kensho.com/api/v2/search

Authentication

Go to https://grounding-alpha.preview.kensho.com/login (opens in a new tab) and follow the instructions until you reach a page displaying "Logged in as <your email>".
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.
Use the access token as Bearer authentication in your API requests.

Code Examples

cURL

Python

curl -X POST https://grounding-alpha.preview.kensho.com/api/v2/search \
    -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -H "Content-Type: application/json" \
    -d '{"query": "What is Apple'\''s P/E ratio?"}'

Request Parameters

Parameter	Type	Required	Description
`query`	string	Yes	The natural language query to search for data
`allowed_datasets`	list[string]	No	Optional list of specific data agent names to query. If not provided, all available data agents will be queried. Valid agent names are returned from the agents endpoint (opens in a new tab).

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.

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-alpha.preview.kensho.com/login (opens in a new tab) again.

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.