Retriever Service - API Reference

The query string for retrieval, e.g. "What is the capital of France?"

The desired level for community schema retrieval (if applicable). Defaults to 2 if not provided.

The type of query to perform: GLOBAL, LOCAL, UNIFIED, or CUSTOM. If not specified, defaults to GLOBAL.

Instructions passed to the LLM to specify a custom response generation style (e.g "Short answer", "Multiple paragraphs", "Sarcastic answer", etc.). If not specified, uses the default response types specified by the Local & Global & Unified Query Parameters.

Whether to include metadata in the response. If not specified, defaults to false.

Whether to use the LLM planner for intelligent query processing. If true, the LLM planner will orchestrate the query using both local and global retrievers. If not specified, defaults to true for LOCAL queries.

Optional parameter to filter retrieval by specific partition IDs. Cannot be combined with auto_select_partitions.

Whether to use the cache for this query. If true, checks cache for hits and saves responses to cache. If false, skips cache entirely (no check, no write). If not specified, defaults to false.

Whether to show inline citations in the response. If true, citations will be formatted as [[X](URL)] or [X] in the response. If false, all [CITE:X] patterns will be removed from the response. If not specified, defaults to true. Note: For deep search queries (use_llm_planner=true), citations are always disabled.

Custom prompts to override default system prompts. Maps prompt keys to custom prompt strings. Only specified prompts are overridden; others use defaults. Valid keys: local_rag_response, global_reduce_rag_response, global_map_rag_points, ds_generate_plan, ds_step_query, ds_completion_check, ds_final_synthesis, no_relevant_data_message.

Custom tools for advanced retrieval scenarios. List of tool IDs for explicit custom retriever execution with query_type=CUSTOM. When provided with CUSTOM query type, these custom retrievers will be executed directly. Format: ["chunk_context_expander_v1", "hybrid_search_and_expand_communities_v1"]

CUSTOM index/view creation. Tool config takes precedence over this field; if neither is set, missing indexes/views are created automatically.

Optional per-query chat model override. If provided, this model is used instead of the deploy-time default for this query only. If empty/omitted, the deploy-time default model is used (current behavior). Embedding model is never affected by this field.

Optional UI routing alias. When set, mode overrides query_type/use_llm_planner: INSTANT -> query_type=UNIFIED, use_llm_planner=false DEEP_SEARCH -> query_type=CUSTOM, use_llm_planner=true

If omitted or true, the service will search the AutoGraph corpus graph to select relevant partition IDs automatically. Set false to disable. Cannot be combined with partition_ids.

The textual result of the retrieval process.

Optional additional metadata about the result, if needed in the future.

Identifier of the persisted query run.

Empty on success. On failure: the same machine-readable code the model-config endpoint returns, so a provider problem hit mid-query (INSUFFICIENT_QUOTA, INVALID_API_KEY, KEY_EXPIRED, MODEL_NOT_FOUND, ...) reads the same as one caught while saving credentials. Falls back to PROCESSING_ERROR for failures that are not provider failures.

Token/partial text chunk

Final full result text (populated on the last chunk)

Optional metadata (can be incremental or final, JSON-encoded if needed)

True on the last chunk

Identifier of the persisted query run.

Empty on success. Same codes as GraphRAGQueryResponse.error_code, set on the chunk that reports the failure.

Current health status (e.g. "OK", "BAD")

Optional detailed message about health status.

Optional cap on the number of runs returned (0 = no explicit limit).

True if credentials were successfully validated and persisted.

True if all validation checks passed.

True if config was applied to the running pod (no restart needed).

"valid" | "invalid" | "expired" | "rate_limited" | "insufficient_quota", or "" when the live probe could not tell (endpoint unreachable, timeout, or the request failed before the probe ran).

On validation failure: which field failed.

On validation failure: machine-readable error code. Request errors: PROJECT_MISMATCH, PROVIDER_REQUIRED, INVALID_PROVIDER, PROVIDER_MISMATCH, MODEL_REQUIRED, SECRET_PROFILE_REQUIRED, SECRET_NOT_FOUND, SECRET_RESOLUTION_ERROR, SECRET_PROFILE_INVALID. Live probe errors: INVALID_API_KEY, KEY_EXPIRED, INSUFFICIENT_QUOTA, RATE_LIMITED, PERMISSION_DENIED, MODEL_NOT_FOUND, MODEL_REJECTED_REQUEST, ENDPOINT_UNREACHABLE, TIMEOUT, PROVIDER_ERROR, PROVIDER_EMPTY_RESPONSE, API_KEY_REQUIRED, INVALID_BASE_URL, UNKNOWN_VALIDATION_ERROR. Persistence errors: METADATA_CLIENT_UNAVAILABLE, METADATA_WRITE_TIMEOUT, METADATA_WRITE_FAILED, SERVICE_NOT_REGISTERED.

On validation failure: human-readable message.

Metadata returned for this run.

GLOBAL | LOCAL | UNIFIED | CUSTOM

streaming | complete | error

JSON string of the query parameters used

"openai" | "custom" — required

"openai" | "custom" — required