> ## Documentation Index > Fetch the complete documentation index at: https://docs.contextual.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get Agent Metadata > Get metadata and configuration of a given `Agent`. ## OpenAPI ````yaml api-reference/openapi.json get /agents/{agent_id}/metadata openapi: 3.1.0 info: title: Endpoints version: '1.0' servers: - url: https://api.contextual.ai/v1 security: - BearerAuth: [] paths: /agents/{agent_id}/metadata: get: tags: - /agents summary: Get Agent Metadata description: Get metadata and configuration of a given `Agent`. operationId: get_agent_metadata_agents__agent_id__metadata_get parameters: - name: agent_id in: path required: true schema: type: string format: uuid description: ID of the agent for which to retrieve details title: Agent Id description: ID of the agent for which to retrieve details responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/GetAgentResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: GetAgentResponse: properties: name: type: string title: Name description: Name of the agent description: type: string title: Description description: Description of the agent datastore_ids: items: type: string format: uuid type: array title: Datastore Ids description: The IDs of the datastore(s) associated with the agent template_name: type: string title: Template Name description: The template used to create this agent. system_prompt: type: string title: System Prompt description: >- Instructions that your agent references when generating responses. Note that we do not guarantee that the system will follow these instructions exactly. filter_prompt: type: string title: Filter Prompt description: >- The prompt to an LLM which determines whether retrieved chunks are relevant to a given query and filters out irrelevant chunks. This prompt is applied per chunk. no_retrieval_system_prompt: type: string title: No Retrieval System Prompt description: >- Instructions on how the agent should respond when there are no relevant retrievals that can be used to answer a query. multiturn_system_prompt: type: string title: Multiturn System Prompt description: >- Instructions on how the agent should handle multi-turn conversations. suggested_queries: items: type: string type: array title: Suggested Queries description: >- These queries will show up as suggestions in the Contextual UI when users load the agent. We recommend including common queries that users will ask, as well as complex queries so users understand the types of complex queries the system can handle. The max length of all the suggested queries is 1000. agent_configs: $ref: '#/components/schemas/AgentConfigs' title: Agent Configs description: >- The following advanced parameters are experimental and subject to change. type: object required: - name - datastore_ids - template_name title: GetAgentResponse description: Response to GET Agent request HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AgentConfigs: properties: retrieval_config: $ref: '#/components/schemas/RetrievalConfig' title: Retrieval Config description: Parameters that affect how the agent retrieves from datastore(s) filter_and_rerank_config: $ref: '#/components/schemas/FilterAndRerankConfig' title: Filter And Rerank Config description: >- Parameters that affect filtering and reranking of retrieved knowledge generate_response_config: $ref: '#/components/schemas/GenerateResponseConfig' title: Generate Response Config description: Parameters that affect response generation global_config: $ref: '#/components/schemas/GlobalConfig' title: Global Config description: Parameters that affect the agent's overall RAG workflow reformulation_config: $ref: '#/components/schemas/ReformulationConfig' title: Reformulation Config description: Parameters that affect the agent's query reformulation acl_config: $ref: '#/components/schemas/ACLConfig' title: Acl Config description: Parameters that affect the agent's Agent Composer workflow translation_config: $ref: '#/components/schemas/TranslationConfig' title: Translation Config description: Parameters that affect the agent's translation workflow type: object title: AgentConfigs description: Response to configs for different components ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError RetrievalConfig: properties: top_k_retrieved_chunks: type: integer title: Top K Retrieved Chunks description: The maximum number of retrieved chunks from the datastore. ge: 1 le: 200 lexical_alpha: type: number title: Lexical Alpha description: >- The weight of lexical search during retrieval. Must sum to 1 with semantic_alpha. le: 1 semantic_alpha: type: number title: Semantic Alpha description: >- The weight of semantic search during retrieval. Must sum to 1 with lexical_alpha. le: 1 type: object title: RetrievalConfig description: Captures Retrieval configurations for an Agent FilterAndRerankConfig: properties: top_k_reranked_chunks: type: integer title: Top K Reranked Chunks description: The number of highest ranked chunks after reranking to be used reranker_score_filter_threshold: type: number maximum: 1 minimum: 0 title: Reranker Score Filter Threshold description: >- If the reranker relevance score associated with a chunk is below this threshold, then the chunk will be filtered out and not used for generation. Scores are between 0 and 1, with scores closer to 1 being more relevant. Set the value to 0 to disable the reranker score filtering. default: 0 rerank_instructions: type: string title: Rerank Instruction description: >- Instructions that the reranker references when ranking retrievals. Note that we do not guarantee that the reranker will follow these instructions exactly. Examples: "Prioritize internal sales documents over market analysis reports. More recent documents should be weighted higher. Enterprise portal content supersedes distributor communications." and "Emphasize forecasts from top-tier investment banks. Recent analysis should take precedence. Disregard aggregator sites and favor detailed research notes over news summaries." default_metadata_filters: anyOf: - $ref: '#/components/schemas/BaseMetadataFilter' - $ref: '#/components/schemas/CompositeMetadataFilter' title: Default Metadata Filters description: >- Optional metadata filter which is applied while retrieving from every datastore linked to this agent. examples: - filters: - field: field1 operator: equals value: value1 operator: AND per_datastore_metadata_filters: additionalProperties: $ref: '#/components/schemas/CompositeMetadataFilter' type: object title: Per Datastore Metadata Filters description: >- Defines an optional custom metadata filter per datastore ID. Each entry in the dictionary should have a datastore UUID as the key, and the value should be a metadata filter definition. The filter will be applied in addition to filter(s) specified in `default_metadata_filters` and in the `documents_filters` field in the `/query` request during retrieval. examples: - d49609d9-61c3-4a67-b3bd-5196b10da560: filters: - field: field1 operator: equals value: value1 operator: AND type: object title: FilterAndRerankConfig description: Captures Filter and Rerank configurations for an Agent GenerateResponseConfig: properties: model: $ref: '#/components/schemas/GenerationModelName' title: Model description: The model to use for response generation. max_new_tokens: type: integer title: Max New Tokens description: The maximum number of tokens the model can generate in a response. temperature: type: number title: Temperature description: >- The sampling temperature, which affects the randomness in the response. ge: 0 le: 1 top_p: type: number title: Top P description: >- A parameter for nucleus sampling, an alternative to `temperature` which also affects the randomness of the response. ge: 0 le: 1 frequency_penalty: type: number title: Frequency Penalty description: >- This parameter adjusts how the model treats repeated tokens during text generation. seed: type: integer title: Seed description: >- This parameter controls the randomness of how the model selects the next tokens during text generation. calculate_groundedness: type: boolean title: Calculate Groundedness description: This parameter controls generation of groundedness scores. avoid_commentary: type: boolean title: Avoid Commentary description: >- Flag to indicate whether the model should avoid providing additional commentary in responses. Commentary is conversational in nature and does not contain verifiable claims; therefore, commentary is not strictly grounded in available context. However, commentary may provide useful context which improves the helpfulness of responses. default: false additionalProperties: false type: object title: GenerateResponseConfig description: Captures advance LLM configurations for an Agent GlobalConfig: properties: enable_rerank: type: boolean title: Enable Rerank description: Enables reranking of retrieved chunks enable_filter: type: boolean title: Enable Filter description: Enables filtering of retrieved chunks with a separate LLM enable_multi_turn: type: boolean title: Enable Multi Turn description: >- Enables multi-turn conversations. This feature is currently experimental and will be improved. should_check_retrieval_need: type: boolean title: Should Check Retrieval Need description: >- Enables checking if retrieval is needed for the query. This feature is currently experimental and will be improved. additionalProperties: false type: object title: GlobalConfig description: Captures global configs ReformulationConfig: properties: enable_query_expansion: type: boolean title: Enable Query Expansion description: Whether to enable query expansion. query_expansion_prompt: type: string title: Query Expansion Prompt description: The prompt to use for query expansion. enable_query_decomposition: type: boolean title: Enable Query Decomposition description: Whether to enable query decomposition. query_decomposition_prompt: type: string title: Query Decomposition Prompt description: The prompt to use for query decomposition. type: object title: ReformulationConfig description: Captures Query Reformulation configurations for an Agent ACLConfig: properties: acl_active: type: boolean title: Acl Active description: Deprecated field. To be removed in the future. acl_yaml: type: string title: Acl Yaml description: The YAML file to use for Agent Composer. type: object title: ACLConfig description: Captures Agent Composer configurations for an Agent TranslationConfig: properties: translate_needed: type: boolean title: Translate Needed description: Whether to enable translation for the agent's responses. translate_confidence: type: number title: Translate Confidence description: The confidence threshold for translation. type: object title: TranslationConfig description: Captures Translation configurations for an Agent BaseMetadataFilter: properties: field: type: string title: Field description: Field name to search for in the metadata operator: $ref: '#/components/schemas/FilterMetadataOperator' description: Operator to be used for the filter. value: anyOf: - type: string - type: integer - type: number - type: boolean - items: anyOf: - type: string - type: integer - type: number - type: boolean type: array - type: 'null' title: Value description: >- The value to be searched for in the field. In case of exists operator, it is not needed. type: object required: - field - operator title: BaseMetadataFilter description: >- Defines a custom metadata filter. The expected input is a dict which can have different operators, fields and values. For example: {"field": "title", "operator": "startswith", "value": "hr-"} Use **lowercase** for `value` when not using `equals` operator. For document_id and date_created the query is built using direct query without nesting. CompositeMetadataFilter: properties: filters: items: anyOf: - $ref: '#/components/schemas/BaseMetadataFilter' - $ref: '#/components/schemas/CompositeMetadataFilter' type: array title: Filters description: 'Filters added to the query for filtering docs ' operator: anyOf: - $ref: '#/components/schemas/CompositeOperator' - type: 'null' description: Composite operator to be used to combine filters type: object required: - filters title: CompositeMetadataFilter description: >- "Defines a custom metadata filter as a Composite MetadataFilter. Which can be be a list of filters or nested filters. GenerationModelName: type: string enum: - Contextual GLM - Gemini 2.5 Pro - Gemini 2.5 Flash - Gemini 2.0 Flash - Gemini 2.0 Flash Lite - Gemini 3 Flash - Gemini 3 Pro - Claude Opus 4 - Claude Sonnet 4 - GPT-5 - Default title: GenerationModelName description: User-facing model names for API requests. FilterMetadataOperator: type: string enum: - equals - containsany - exists - startswith - gt - gte - lt - lte - notequals - between - wildcard title: FilterMetadataOperator CompositeOperator: type: string enum: - AND - OR - AND_NOT title: CompositeOperator securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key ````