---
type: api
title: Describe an AI Index
description: **Spaces method and path for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/operation/operation-get-context-engine-ai-index-aiindexid-describe
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/operation/operation-get-context-engine-ai-index-aiindexid-describe
products:
  - Kibana
---

# Describe an AI Index

Availability:

- Server: `https://{kibana_url}`

## Paths

- `GET` `/api/context_engine/ai_index/{aiIndexId}/_describe`
- `GET` `/s/{space_id}/api/context_engine/ai_index/{aiIndexId}/_describe`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/authentication#apikeyauth)

#### Path Parameters

- `aiIndexId` (string · min: 1 · max: 256)
  The unique identifier of the AI Index.

## Description

Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.

Returns a free-form text context block for an agent. The block describes the AI Index and its ES|QL target. It also includes up to 500 fields exposed by the backing indices, identifies which fields are semantic, provides knowledge item type and tag counts for the current space, and includes example ES|QL queries.

The API reads data as the current user. Elasticsearch index privileges limit which indices the current user can access. A caller who cannot read the backing indices gets a 403 response.

The space comes from the request URL (`/s/{spaceId}/…`) or defaults to the default space. It cannot be specified in any other way.

Returns a 404 response when Context Engine is turned off in this space (`contextEngine:enabled`).

**For more information, refer to the [Context Engine documentation](https://www.elastic.co/docs/explore-analyze/ai-features/context-engine).**<br/><br/>[Required authorization] Route required privileges: contextEngine:read.

## Responses

#### `200`

A free-form text context block describing the AI Index.

`application/json`

- `response` (string)
  Free-form text context block describing the AI Index for an agent.
#### `400`

The description response exceeded the size limit.

`application/json`

- `error` (string)
  The HTTP status text.
- `message` (string)
  A human-readable error message.
- `statusCode` (number)
  The HTTP status code.
#### `403`

The caller cannot read the backing indices. Describing an AI Index requires the `read` and `view_index_metadata` index privileges on them.

`application/json`

- `error` (string)
  The HTTP status text.
- `message` (string)
  A human-readable error message.
- `statusCode` (number)
  The HTTP status code.
#### `404`

No AI Index with the given ID exists in the current space, or Context Engine is turned off in this space.

`application/json`

- `error` (string)
  The HTTP status text.
- `message` (string)
  A human-readable error message.
- `statusCode` (number)
  The HTTP status code.
## Code Examples

#### Console

```console
GET kbn:/api/context_engine/ai_index/customer_support/_describe
```

#### curl

```curl
curl \
  -X GET "https://${KIBANA_URL}/api/context_engine/ai_index/customer_support/_describe" \
  -H "Authorization: ApiKey ${API_KEY}"
```

## Response Examples

#### Context block for an agent

Example response with a context block for an agent

```json
{
  "response": "AI index: customer_support\nKnowledge about customer support cases.\nQuery with ES|QL against: ai-index-ds-customer-support\n\nFields\n@timestamp: date, searchable, aggregatable\ncontent: text, searchable\ncontent.semantic: semantic_text, searchable\ndescription: text, searchable\ndescription.semantic: semantic_text, searchable\ntags: keyword, searchable, aggregatable\ntitle: text, searchable\ntitle.semantic: semantic_text, searchable\ntype: keyword, searchable, aggregatable\n\nSemantic fields\ncontent.semantic\ndescription.semantic\ntitle.semantic\n\nKnowledge item types\n\u0022faq\u0022: 12\n\u0022runbook\u0022: 4\n\nTags\n\u0022billing\u0022: 7\n\u0022password\u0022: 5\n\nExample queries (adapt field names for non-canonical indices)\n\nFull text search, lexical and semantic fused together (?query)\nFROM ai-index-ds-customer-support METADATA _id, _index, _score\n| FORK\n    ( WHERE MATCH(title, ?query) OR MATCH(description, ?query) OR MATCH(content, ?query) | SORT _score DESC | LIMIT 20 )\n    ( WHERE MATCH(title.semantic, ?query) OR MATCH(description.semantic, ?query) OR MATCH(content.semantic, ?query) | SORT _score DESC | LIMIT 20 )\n| FUSE\n| SORT _score DESC, _id ASC\n| KEEP title, description, content, type, tags\n| LIMIT 5\n\nFilter by knowledge item type and tag (?type, ?tag; tags is multi-valued, so MATCH)\nFROM ai-index-ds-customer-support\n| WHERE type == ?type AND MATCH(tags, ?tag)\n| KEEP title, description, content, type, tags\n| LIMIT 20\n\nCount by type\nFROM ai-index-ds-customer-support\n| STATS count = COUNT(*) BY type\n| SORT count DESC\n| LIMIT 20"
}
```

#### Response too large

The field metadata for the backing indices exceeded the size limit

```json
{
  "error": "Bad Request",
  "message": "Field metadata for the AI index exceeded the maximum allowed size of 20MB. Point the AI index at fewer or smaller indices.",
  "statusCode": 400
}
```

#### Missing view_index_metadata privilege

The caller can read the backing indices but cannot read their mappings

```json
{
  "error": "Forbidden",
  "message": "security_exception\n\tRoot causes:\n\t\tsecurity_exception: action [indices:admin/mappings/get] is unauthorized for user [jdoe] with effective roles [support_reader] on indices [ai-index-ds-customer-support], this action is granted by the index privileges [view_index_metadata,manage,all]",
  "statusCode": 403
}
```

#### Backing indices not readable

The caller cannot read the backing indices of the AI Index

```json
{
  "error": "Forbidden",
  "message": "AI index \u0027customer_support\u0027 is not readable. Reading it needs the Elasticsearch \u0027read\u0027 and \u0027view_index_metadata\u0027 privileges on its backing indices.",
  "statusCode": 403
}
```

#### Context Engine turned off

Context Engine is turned off in this space

```json
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 404
}
```

#### AI Index not found

No AI Index with the given ID exists in the current space

```json
{
  "error": "Not Found",
  "message": "AI index \u0027customer_support\u0027 not found",
  "statusCode": 404
}
```