---
title: "Get a query history"
method: GET
path: "/v2/queries/{query_id}"
tags: ["Query History"]
---

# Get a query history

`GET /v2/queries/{query_id}`

Returns the detailed history of a specific query made against a corpus. The response includes the query latency, the execution time, and the stages of the query pipeline.

Set the `query_id` path parameter. The response includes the `id` of the query, the `query` object, the `chat_id`, timing information, and the `spans` object.

## Path parameters

- `query_id` string, required

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Response `200`

The query history. The `spans` object describes the ordered stages of the query pipeline and what happens during each stage.

- QueryHistory — A complete record of a previously executed query, including the request parameters and response.
  - `id` string, required — The ID of the query history.
  - `query` QueryRequest — Query one or more corpora.
    - `query` string, required — The search query string, which is the question the user is asking.
    - `search` SearchCorporaParameters, required — Search parameters to retrieve knowledge for the query.
      - `corpora` KeyedSearchCorpus[], required — The corpora that you want to search.
        - `custom_dimensions` CustomDimensions, nullable — The custom dimensions as additional weights.
        - `metadata_filter` string — The filter string that narrows the search based on metadata attributes. The query against this corpus returns only document parts that match the `metadata_filter`. You can filter only metadata fields set as `filter_attributes` on the corpus. Filter syntax is similar to a SQL WHERE clause. See [metadata filters documentation](https://docs.vectara.com/docs/learn/metadata-search-filtering/filter-overview) for more information.
        - `lexical_interpolation` number, float — The weight of lexical scores compared to the embedding score. A value of 0 disables lexical search. A value of 1 uses only lexical search.
        - `semantics` 'default' | 'query' | 'response' — Indicates whether to consider a query against this corpus as a query or a response.
        - `corpus_key` string, required — A user-provided key for a corpus.
        - `query` string — The query for a particular corpus. If present, it overrides the overall query.
      - `offset` integer — The number of results to skip. Use this for pagination.
      - `limit` integer — The maximum number of results returned.
      - `context_configuration` ContextConfiguration — Configuration for the presentation of each document part in the result set. Use either `characters_before`/`characters_after` or `sentences_before`/`sentences_after`; if both are set, `sentences_*` takes precedence. Setting `full_document_context: true` overrides both and returns the entire matching document as context.
        - `characters_before` integer — The number of characters to show before the matching document part. This shows the context of the part in the wider document. Ignored if `sentences_before` is set. The platform captures the full sentence that contains the captured characters, so a truncated word or sentence does not lose meaning.
        - `characters_after` integer — The number of characters to show after the matching document part. This shows the context of the part in the wider document. Ignored if `sentences_after` is set. The platform captures the full sentence that contains the captured characters, so a truncated word or sentence does not lose meaning.
        - `sentences_before` integer — The number of sentences to show before the matching document part. This shows the context of the part in the wider document.
        - `sentences_after` integer — The number of sentences to show after the matching document part. This shows the context of the part in the wider document.
        - `start_tag` string — The tag that wraps the start of the document part. Use an HTML/XML tag or another delimiter. Your application can use the tag to highlight the part in your UI. The tag also marks where the preceding context ends and the document part begins.
        - `end_tag` string — The tag that wraps the end of the document part. Use an HTML/XML tag or another delimiter. Your application can use the tag to highlight the part in your UI. The tag also marks where the document part ends and the following context begins.
        - `full_document_context` boolean — When true, the platform returns the entire document that contains the matching part as context. `characters_before`/`characters_after` and `sentences_before`/`sentences_after` are ignored.
      - `reranker` union — Reranks the results of the search. Rerankers improve the order of search results. By default, the search uses the most powerful reranker available to the customer's plan. To disable reranking, set the reranker `type` to `"none"`.
        - object — Reranker that is specific to the customer.
          - `type` string — When the type is `customer_reranker`, you can specify the `reranker_name` of a reranker. `reranker_id` is deprecated. The search then reranks results with that reranker.
          - `reranker_id` string — The ID of the reranker. The multilingual reranker that may be specified is rnk_272725719. Do not specify the MMR reranker ID here, and instead, use the MMR reranker object type. **Deprecated**: Use `reranker_name` instead.
          - `reranker_name` string — The name of the reranker. Do not specify the MMR reranker name here. Instead, use the MMR reranker object type.
          - `limit` integer — The maximum number of results to return after the reranking process. When you apply a reranker, it performs these steps: 1. Reranks all input results according to its algorithm. 2. Sorts the reranked results by their new scores. 3. Returns the top N results, where N is the value of this limit. Note: This limit applies per reranking stage. In a chain of rerankers, each reranker can have its own limit. This can reduce the number of results at each stage.
          - `cutoff` number, float — The minimum score threshold for results to be included after the reranking process. When you apply a reranker with a cutoff, it performs these steps: 1. Reranks all input results according to its algorithm. 2. Removes any results with scores below the cutoff. 3. Returns the remaining results, sorted by their new scores. Note: This cutoff applies per reranking stage. In a chain of rerankers, each reranker can have its own cutoff. This can further reduce the number of results at each stage. If you specify both `limit` and `cutoff`, the cutoff applies first, then the limit.
          - `include_context` boolean — If true, the reranker uses text with context (see `context_configuration`) for scoring.
          - `instructions` string — Instructions for instruction-following rerankers that guide relevance scoring behavior. Only applicable to rerankers that support custom instructions.
        - object — A reranker that uses user-defined functions to reorder search results.
          - `type` string — When the type is `userfn`, you can define custom reranking functions using document-level metadata, part-level metadata, or scores generated from the request-level metadata.
          - `user_function` string — The user defined function.
          - `limit` integer — The maximum number of results to return after the reranking process. When you apply a reranker, it performs these steps: 1. Reranks all input results according to its algorithm. 2. Sorts the reranked results by their new scores. 3. Returns the top N results, where N is the value of this limit. Note: This limit applies per reranking stage. In a chain of rerankers, each reranker can have its own limit. This can reduce the number of results at each stage.
          - `cutoff` number, float — The minimum score threshold for results to be included after the reranking process. When you apply a reranker with a cutoff, it performs these steps: 1. Reranks all input results according to its algorithm. 2. Removes any results with scores below the cutoff. 3. Returns the remaining results, sorted by their new scores. Note: This cutoff applies per reranking stage. In a chain of rerankers, each reranker can have its own cutoff. This can further reduce the number of results at each stage. If you specify both `limit` and `cutoff`, the cutoff applies first, then the limit.
        - object — A reranker that uses Maximal Marginal Relevance to balance relevance and diversity in search results.
          - `type` string — When the type is `mmr`, you can specify the `diversity_bias`. The search then uses the MMR reranker.
          - `diversity_bias` number, float — The diversity bias. Higher values indicate more diversity.
          - `limit` integer — The maximum number of results to return after the reranking process. When you apply a reranker, it performs these steps: 1. Reranks all input results according to its algorithm. 2. Sorts the reranked results by their new scores. 3. Returns the top N results, where N is the value of this limit. Note: This limit applies per reranking stage. In a chain of rerankers, each reranker can have its own limit. This can reduce the number of results at each stage.
          - `cutoff` number, float — The minimum score threshold for results to be included after the reranking process. When you apply a reranker with a cutoff, it performs these steps: 1. Reranks all input results according to its algorithm. 2. Removes any results with scores below the cutoff. 3. Returns the remaining results, sorted by their new scores. Note: This cutoff applies per reranking stage. In a chain of rerankers, each reranker can have its own cutoff. This can further reduce the number of results at each stage. If you specify both `limit` and `cutoff`, the cutoff applies first, then the limit.
        - object — A reranker that applies multiple rerankers in sequence to produce the final search results.
          - `type` string — When the type is `chain`, you can chain rerankers together.
          - `rerankers` SearchReranker[], required — An array of rerankers to apply to the search results in sequence.
        - object — A placeholder reranker that does not modify the original search results ordering.
          - `type` string — When the type is `none`, the search applies no reranking.
          - `limit` integer — The maximum number of results to return after the reranking process. When you apply a reranker, it performs these steps: 1. Reranks all input results according to its algorithm. 2. Sorts the reranked results by their new scores. 3. Returns the top N results, where N is the value of this limit. Note: This limit applies per reranking stage. In a chain of rerankers, each reranker can have its own limit. This can reduce the number of results at each stage.
      - `max_by` 'doc.id' — Collapses the result set to return at most one result per document. Keeps the highest-scoring part of each document. Applies to the retrieved results before reranking and pagination, so the number of results returned can be smaller than `limit`.
    - `generation` GenerationParameters — The parameters to control generation.
      - `enabled` boolean — Whether generation is enabled for this query. Chat requests ignore this field.
      - `generation_preset_name` string — The name of the generation preset that supplies default values for generation. A `generation_preset` is an object with a bundle of properties that specifies: * The `prompt_template` that is rendered and then sent to the LLM. * The LLM to use. * `model_parameter`s such as temperature. You can override any of these properties by setting them in this object. Set `model_parameters.llm_name` to override the model that `generation_preset_name` selects. If `generation_preset_name` is not set, the platform uses the default model and prompt.
      - `prompt_name` string — Use `generation_preset_name` instead of `prompt_name`.
      - `max_used_search_results` integer — The maximum number of search results available to the prompt.
      - `prompt_template` string — The template that renders the prompt sent to the generative LLM. By default, the platform manages the system and user roles and prompts for the generative LLM. Set this field to override the default prompts. The `prompt_template` is an Apache Velocity template. For details on how to configure the `prompt_template`, see the [long-form documentation](https://docs.vectara.com/docs/prompts/vectara-prompt-engine).
      - `prompt_text` string — Deprecated. Use `prompt_template` instead. If `prompt_template` is set, the platform ignores this property.
      - `max_response_characters` integer — Controls the length of the generated output. This is a rough estimate and not a hard limit: the end output can be longer or shorter than this value. The platform includes `max_response_characters` in the prompt, so the LLM's instruction-following capability dictates how closely the output stays within the limit.
      - `response_language` 'auto' | 'eng' | 'deu' | 'fra' | 'zho' | 'kor' | 'ara' | 'rus' | 'tha' | 'nld' | 'ita' | 'por' | 'spa' | 'jpn' | 'pol' | 'tur' | 'vie' | 'ind' | 'ces' | 'ukr' | 'ell' | 'heb' | 'fas' | 'hin' | 'urd' | 'swe' | 'ben' | 'msa' | 'ron' — Languages that the platform supports.
      - `model_parameters` object — The parameters for the model. WARNING: This is an experimental feature that can change at any point with virtually no notice. Use it to converge on optimal parameters, then set them in the prompt definitions.
        - `llm_name` string — The model (e.g., `gpt-4`) to use for summarization. If set, it overrides the model that `generation_preset_name` selects.
        - `max_tokens` integer — The maximum number of tokens that the model returns.
        - `temperature` number, float — The sampling temperature to use. Higher values make the output more random, while lower values make it more focused and deterministic.
        - `frequency_penalty` number, float — Higher values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
        - `presence_penalty` number, float — Higher values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.
      - `citations` CitationParameters — Style the generator should use when making citations.
        - `style` 'none' | 'numeric' | 'html' | 'markdown' — The citation style that you want to use in the summary: * `numeric` - Citations formatted as simple numerals: \[1\], \[2\], etc. * `none` - Citations removed from text. * `html` - Citation formatted as a URL like `<a href="url_pattern">text_pattern</a>`. * `markdown` - Formatted as `[text_pattern](url_pattern)`.
        - `url_pattern` string — The URL pattern if the citation_style is set to `html` or `markdown`. The pattern can access metadata attributes in the document or part. e.g. `https://my.doc/foo/{doc.id}/{part.id}` The default `url_pattern` is an empty string.
        - `text_pattern` string — The text pattern if the citation_style is set to `html` or `markdown`. For HTML, this pattern sets the href. For markdown, it sets the text within `[]`. If not set, the text defaults to `N`, the index of the result. The default citation style looks like `[N](<url_pattern>)` for markdown. You can use metadata attributes in the `text_pattern`. For example, the pattern `{doc.title}` with citation style `markdown` produces citation output like `[Title](<url_pattern>)` when the document's metadata includes `{"title":"Title"}`.
      - `enable_factual_consistency_score` boolean — Whether to return the factual consistency score with query results.
    - `stream_response` boolean — Indicates whether to stream the response.
    - `save_history` boolean — Indicates whether to save the query to query history.
    - `intelligent_query_rewriting` boolean — [Tech Preview] Indicates whether to enable intelligent query rewriting. When enabled, the platform attempts to extract metadata filters and rewrite the query to improve search results. See [intelligent query rewriting](https://docs.vectara.com/docs/search-and-retrieval/intelligent-query-rewriting) for more details.
  - `chat_id` string — The ID of the chat the query is a part of.
  - `latency_millis` integer — Time taken to complete the query, measured in milliseconds.
  - `started_at` string, date-time — ISO date time indicating when the query was first received.
  - `agent_key` string — The agent key if this query was made through an agent.
  - `session_key` string — The session key if this query was made through an agent session.
  - `spans` QueryHistorySpan[] — Parts of the query pipeline. Each span explains what happened during that stage of the query pipeline.
    - union — Portion of the query history.
      - object — The rephrase stage of the query pipeline. The platform can rephrase the query to better suit the corpus.
        - `type` string — This value is always `rephrase`.
        - `latency_millis` integer — Time taken in milliseconds.
        - `started_at` string, date-time — When the span started.
        - `rephrased_query` string — Query made to the corpora.
      - object — The search portion of the query pipeline. This occurs before any reranking span.
        - `type` string — This value is always `search`.
        - `latency_millis` integer — Time taken in milliseconds.
        - `started_at` string, date-time — ISO date time that indicates when the span started.
        - `search_results` IndividualSearchResult[] — The search results before reranking.
          - union — A ranked search result from a query. Discriminated by result_type.
            - object — Common fields for all search result types.
              - …
            - object — Common fields for all search result types.
              - …
      - object — The reranking of the search result.
        - `type` string — This value is always `rerank`.
        - `latency_millis` integer — Time taken in milliseconds.
        - `started_at` string, date-time — When the span started.
        - `reranked_search_results` RerankedSearchResult[] — The new search results after reranking.
          - `text` string — The document part that matches the query, altered by the context configuration.
          - `score` number, double — The score of the individual result.
          - `original_score` number, double — The original score of the individual result before reranking.
      - object — The generation by an LLM.
        - `type` string — This value is always `generation`.
        - `latency_millis` integer — Time taken in milliseconds.
        - `started_at` string, date-time — When the span started.
        - `prompt` string — The text sent as a prompt to the LLM.
        - `generation` string — The text generated from the LLM.
      - object — The factual consistency of the generation.
        - `type` string — This value is always `fcs`.
        - `latency_millis` integer — Time taken in milliseconds.
        - `started_at` string, date-time — When the span started.
        - `score` number, float — The probability that the summary is factually consistent with the results.
      - object — Provides detailed information about a rewritten query generated for a specific corpus when intelligent query rewriting is enabled.
        - `type` string — Indicates the type of span. This value is always `rewritten_query`.
        - `corpus_key` string — The corpus key that the query was made on.
        - `latency_millis` integer — Time taken in milliseconds.
        - `started_at` string, date-time — ISO date time that indicates when the span started.
        - `warnings` RewrittenQueryWarning[] — Warnings that occurred during query rewriting.
        - `filter_extraction` FilterExtraction — The result of query filter extraction.
          - `query` string — The rephrased form of the input query. The search executes this query.
          - `metadata_filter` string — The metadata filter extracted from the input query.

## Other responses

- `403` — Permissions do not allow retrieving the query history.
- `404` — Query history not found.

---

[API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/revisions/e85040b266cc/schema)