The Aggregated Context API delivers intelligent, context-rich responses from the Alation data catalog based on natural language queries. It can act as the backend service that powers custom-developed AI agents and applications with metadata context, enabling them to surface relevant insights to users.
The Aggregated Context API is available on Alation Cloud Service instances and is enabled by default.
Starting with Alation Backend version 2025.1.5, the API is generally available and includes a free tier. Contact your Account Manager for pricing options beyond the free tier.
The API applies rate limits to support fair usage and protect service quality.
The API takes a natural language question (for example: What certified data assets are used to determine customer retention?), searches the catalog to identify the most relevant data assets, and then structures the response for use by an AI application or agent.
What brewery information is there in the catalog?
{
"relevant_tables": [
{
"title": "Brewery and Beer Data",
"name": "cb_acquisition_targets",
"description": "This is a cleaned list of breweries and beers with their annual revenue and cost. Additional details can be found in the associated documentation or by contacting a data steward."
},
{
"title": "Brewery Revenue Analysis",
"name": "cb_brew_rev_als",
"description": "This table shows the revenue generated by beer by breweries. Breweries are also separated by geography."
}
]
}
The Context API operates in two modes: search (default) and bulk that are specified as API request parameters. The mode parameter defines which mode is used. If omitted, the search mode is applied by default:
search (default): This is a conversational mode where you provide a natural language question. Using a signature in search mode is recommended, but optional.bulk: This mode is for direct object retrieval in bulk operations. The signature object is mandatory and precisely defines the objects to be retrieved. The Documentation object type is not supported in bulk mode, and the optional fields aren’t used.The API currently supports a defined set of object types and fields from the Alation catalog. Supports means that the API response will return context derived specifically from analyzing these object types.
Object Type Default Required Fields Schemaname, title, description, url Table name, title, description, url Column (Attribute) name, title, data_type, url Documentation title, content, url Query title, description, content, url BI folder name, description, bi_object_type, url BI report name, description, bi_object_type, url, bi_fields BI report field name, description, bi_object_type, data_type, role, expression
📘Documentation objects
The Documentation type includes a number of separate documentation object types, such as Document, Document Folder, Article, and Glossary. Documentation objects aren’t supported in the
bulkmode.
Some fields may be associated with a large number of items. To keep the payload focused, the API limits the volume of these fields. This helps keep performance stable and reduces cost when processing the response with the language model.
For example, if a table has 200 columns, the API will return only the top 50 columns based on popularity. Similarly, for fields like common_joins or sample_values, only the top five items by popularity or usage will be included in the response. This ensures that the response remains concise and relevant.
common_joins Top 5 by popularity common_filters Top 5 by popularity columns Top 50 by popularity sample_value Top 5 by usage common_queries Top 50 queries per table object, ranked by the most recently run or edited mentioned_tables The API returns a maximum of 50 tables per query object, selected randomly bi_fields The API returns a maximum of 100 per BI report, selected randomly
You can use the limit key to specify the number of objects to retrieve for each object type.
This API lets you include a signature to control which objects and fields are processed. Signatures are useful when you want to narrow the request to specific object types or skip fields that aren't relevant. They’re especially helpful when building agents for a specific use case, vertical, or line of business.
The signature allows you to define:
search mode).For information on how you can construct a signature that suits your use case, refer to the guide Customize the Aggregated Context API with a Signature .
The Aggregated Context API is subject to rate limits designed to ensure system stability and predictable performance across all users. These limitations are important to understand when planning for large-scale usage or when building automation that depends on consistent API responsiveness.
There are two main types of limits to be aware of:
Limits inherited from LLM services: The Aggregated Context API uses an external language model provider and inherits the rate limits imposed by those services. The provider enforces limits to prevent oversubscription and ensure fair access for all consumers of their hosted models.
Limits from shared internal resources: The Aggregated Context API shares computational resources with Alation’s user interface and internal services. This means API usage draws on the same infrastructure that supports real-time search and catalog browsing within the platform. To maintain a responsive experience for all users, Alation may enforce limits based on the current load and resource availability.
Alation may fine-tune these limits over time to better align with performance targets or customer-specific configurations.
Reach out to Alation Support to discuss tuning options specific to your instance.
When using the Aggregated Context API, your content is handled with strong privacy and security protections:
Alation will always prioritize secure private network connectivity when available.
Customer content processed by the language model is encrypted and stored in accordance with the data residency settings of the deployment region.
When calling the Aggregated Context API, two key inputs are shared with the language model:
The user question is used to identify which object types may be relevant and to support query interpretation and parsing by the language model.
The signature helps dynamically determine which fields to include in the request, allowing the API to tailor results to the most relevant context.
The underlying language model services implement automated abuse detection to identify and mitigate potential misuse, including violations of acceptable use or responsible AI policies. These detection systems are fully automated: no human review or access is involved in processing your inputs or the model's responses.
Some AI-powered features in Alation are not yet available in all supported deployment regions. To broaden access, Alation may route requests to regions where language model support is available.
When cross-region routing is required, requests are initiated from within Alation Cloud Service infrastructure and securely transmitted to the supported region. These requests are encrypted using TLS 1.2 or higher, and where possible, leverage private network channels to maintain strong data protection standards.
The table below outlines the regions where Alation’s AI features are currently available, along with the corresponding fallback or target regions used for processing.
Origin Region Target Region us-east-1 (US East, N. Virginia)us-east-2 (US East, Ohio)
us-east-1 (US East, N. Virginia) ca-central-1 (Canada, Central) ca-central-1 (Canada, Central) us-west-2 (US West, Oregon) us-west-2 (US West, Oregon) ap-northeast-1 (Asia Pacific, Tokyo)ap-southeast-1 (Asia Pacific, Singapore)
ap-southeast-2 (Asia Pacific, Sydney)
ap-southeast-2 (Asia Pacific, Sydney) eu-central-1 (Europe, Frankfurt) eu-central-1 (Europe, Frankfurt) eu-west-1 (Europe, Ireland) eu-west-1 (Europe, Ireland)Updated 17 days ago
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4