Endpoint

View as Markdown

An AI Search endpoint — compute infrastructure that hosts AI Search indexes and serves queries against them. Customers create, query, and delete endpoints; the system manages provisioning, scaling, and health status.

Endpoint object

namestringPublic PreviewIDImmutable: Name of the AI Search endpoint. Server-assigned full resource path (workspaces/{workspace}/endpoints/{endpoint}) on output. On create, the user-supplied short name is conveyed via CreateEndpointRequest.endpoint_id; the server composes the full name and returns it on the response.
Example: docs-endpoint

creatorstringPublic PreviewOutput only: Creator of the endpoint
Example: john@example.com

create_timestringPublic PreviewOutput only: Time the endpoint was created.
Example: 2023-12-08T05:31:52.061Z

update_timestringPublic PreviewOutput only: Time the endpoint was last updated.
Example: 2023-12-08T05:31:52.061Z

endpoint_typestringPublic PreviewImmutable

Type of endpoint. Required on create and immutable thereafter.

Values:

STORAGE_OPTIMIZED
STANDARD

last_updated_userstringPublic PreviewOutput only: User who last updated the endpoint
Example: john@example.com

idstringPublic PreviewOutput only: Unique identifier of the endpoint
Example: c56bf0a9-4929-4bd4-8bd5-d82ca62f9c76

endpoint_statusobjectPublic PreviewOutput only

Current status of the endpoint

Show child attributesHide child attributes

statestringPublic PreviewOutput only

Current lifecycle state of the endpoint. See State for the meaning of each value.

Values:

PROVISIONING
ONLINE
OFFLINE
RED_STATE
YELLOW_STATE
DELETED

Example: PROVISIONING

messagestringPublic PreviewOutput only: Human-readable detail about the endpoint's current state or the reason for a state transition.

index_countint32Public PreviewOutput only: Number of indexes on the endpoint

budget_policy_idstringPublic Preview: The user-selected budget policy id for the endpoint.

effective_budget_policy_idstringPublic PreviewOutput only: The budget policy id applied to the endpoint
Example: 8b0444ff-8b60-48b0-9d31-e391f6126e0f

custom_tagsarray of objectPublic Preview

The custom tags assigned to the endpoint

Show child attributesHide child attributes

keystringPublic Preview: Key field for an AI Search endpoint tag.

valuestringPublic Preview: [Optional] Value field for an AI Search endpoint tag.

throughput_infoobjectPublic PreviewOutput only

Throughput information for the endpoint

Show child attributesHide child attributes

requested_concurrencydoublePublic Preview: The requested concurrency (total CPU) for the endpoint
Example: 10

current_concurrencydoublePublic PreviewOutput only: The current concurrency (total CPU) allocated to the endpoint
Example: 8

current_concurrency_utilization_percentagedoublePublic PreviewOutput only: The current utilization of concurrency as a percentage (0-100)
Example: 75.5

minimal_concurrency_alloweddoublePublic Preview: The minimum concurrency allowed for this endpoint
Example: 2

maximum_concurrency_alloweddoublePublic Preview: The maximum concurrency allowed for this endpoint
Example: 140

change_request_statestringPublic PreviewOutput only

The state of the most recent throughput change request

Values:

CHANGE_SUCCESS
CHANGE_FAILED
CHANGE_REACHED_MINIMUM
CHANGE_REACHED_MAXIMUM
CHANGE_IN_PROGRESS
CHANGE_ADJUSTED

Example: CHANGE_SUCCESS

change_request_messagestringPublic PreviewOutput only: Additional information about the throughput change request
Example: Throughput successfully adjusted to 10 vCPUs

requested_num_replicasint32Public Preview: The requested number of replicas for the endpoint
Example: 2

current_num_replicasint32Public PreviewOutput only: The current number of replicas allocated to the endpoint
Example: 1

scaling_infoobjectPublic PreviewOutput only

Scaling information for the endpoint

Show child attributesHide child attributes

statestringPublic PreviewOutput only

The current state of the scaling change request.

Values:

SCALING_CHANGE_UNSPECIFIED
SCALING_CHANGE_APPLIED
SCALING_CHANGE_IN_PROGRESS

Example: SCALING_CHANGE_APPLIED

requested_target_qpsint64Public Preview: The requested QPS target for the endpoint. Best-effort; the system does not guarantee this QPS will be achieved.
Example: 500

estimated_completion_timestringBetaOutput only: Estimated time at which the in-progress scaling change will complete. The estimate may change as the scaling change progresses. Unset when no scaling change is in progress, when no estimate is available, or when the change is delayed (see delayed_reason).
Example: 2026-10-04T18:00:00Z

phasestringBetaOutput only

Current phase of the in-progress scaling change. Unset when no scaling change is in progress or the phase is not available.

Values:

ADJUSTING_CAPACITY
INITIALIZING_INDEX
ESTIMATING

Example: INITIALIZING_INDEX

index_initialization_percentageint32BetaOutput only: Percentage of index initialization completed, from 0 to 100. Set only during the INITIALIZING_INDEX phase; unset in other phases or when progress is not available.
Example: 40

delayed_reasonstringBetaOutput only

Reason the in-progress scaling change is delayed. When set, estimated_completion_time is unset. Unset when the change is not delayed or no scaling change is in progress.

Values:

CAPACITY_UNAVAILABLE
SCALE_DOWN_BLOCKED
TAKING_LONGER_THAN_EXPECTED

Example: CAPACITY_UNAVAILABLE

target_qps_change_allowed_after_timestringBetaOutput only: Earliest time a new Target QPS change is accepted. Set only while a scaling change is in progress, the change lock is on, and the endpoint has a recorded last throughput change; may be in the past once the lock has expired.
Example: 2026-10-04T18:00:00Z

usage_policy_idstringPublic Preview: The usage policy id applied to the endpoint.

replica_countint32Public Preview: The client-supplied desired number of replicas for the endpoint, applied at create/update time. Mutually exclusive with target_qps.

target_qpsint32Public Preview: Target QPS for the endpoint. Mutually exclusive with replica_count. Best-effort; the system does not guarantee this QPS will be achieved.

View as Markdown

The Endpoint object

{
  "name": "docs-endpoint",
  "creator": "john@example.com",
  "create_time": "2023-12-08T05:31:52.061Z",
  "update_time": "2023-12-08T05:31:52.061Z",
  "endpoint_type": "STORAGE_OPTIMIZED",
  "last_updated_user": "john@example.com",
  "id": "c56bf0a9-4929-4bd4-8bd5-d82ca62f9c76",
  "endpoint_status": {
    "state": "PROVISIONING",
    "message": "string"
  },
  "index_count": 0,
  "budget_policy_id": "string",
  "effective_budget_policy_id": "8b0444ff-8b60-48b0-9d31-e391f6126e0f",
  "custom_tags": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "throughput_info": {
    "requested_concurrency": 10,
    "current_concurrency": 8,
    "current_concurrency_utilization_percentage": 75.5,
    "minimal_concurrency_allowed": 2,
    "maximum_concurrency_allowed": 140,
    "change_request_state": "CHANGE_SUCCESS",
    "change_request_message": "Throughput successfully adjusted to 10 vCPUs",
    "requested_num_replicas": 2,
    "current_num_replicas": 1
  },
  "scaling_info": {
    "state": "SCALING_CHANGE_APPLIED",
    "requested_target_qps": 500,
    "estimated_completion_time": "2026-10-04T18:00:00Z",
    "phase": "INITIALIZING_INDEX",
    "index_initialization_percentage": 40,
    "delayed_reason": "CAPACITY_UNAVAILABLE",
    "target_qps_change_allowed_after_time": "2026-10-04T18:00:00Z"
  },
  "usage_policy_id": "string",
  "replica_count": 0,
  "target_qps": 0
}

Get an AI Search endpoint Public Preview

GET /api/2.0/ai-search/{name=workspaces/*/endpoints/*}

Get details for a single AI Search endpoint.

API scopes: ai-search

Parameters

namestringRequiredpath: Full resource name of the endpoint. Format: workspaces/{workspace_id}/endpoints/{endpoint_id}

Response

Returns the Endpoint object.

View as Markdown

Response

{
  "name": "docs-endpoint",
  "creator": "john@example.com",
  "create_time": "2023-12-08T05:31:52.061Z",
  "update_time": "2023-12-08T05:31:52.061Z",
  "endpoint_type": "STORAGE_OPTIMIZED",
  "last_updated_user": "john@example.com",
  "id": "c56bf0a9-4929-4bd4-8bd5-d82ca62f9c76",
  "endpoint_status": {
    "state": "PROVISIONING",
    "message": "string"
  },
  "index_count": 0,
  "budget_policy_id": "string",
  "effective_budget_policy_id": "8b0444ff-8b60-48b0-9d31-e391f6126e0f",
  "custom_tags": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "throughput_info": {
    "requested_concurrency": 10,
    "current_concurrency": 8,
    "current_concurrency_utilization_percentage": 75.5,
    "minimal_concurrency_allowed": 2,
    "maximum_concurrency_allowed": 140,
    "change_request_state": "CHANGE_SUCCESS",
    "change_request_message": "Throughput successfully adjusted to 10 vCPUs",
    "requested_num_replicas": 2,
    "current_num_replicas": 1
  },
  "scaling_info": {
    "state": "SCALING_CHANGE_APPLIED",
    "requested_target_qps": 500,
    "estimated_completion_time": "2026-10-04T18:00:00Z",
    "phase": "INITIALIZING_INDEX",
    "index_initialization_percentage": 40,
    "delayed_reason": "CAPACITY_UNAVAILABLE",
    "target_qps_change_allowed_after_time": "2026-10-04T18:00:00Z"
  },
  "usage_policy_id": "string",
  "replica_count": 0,
  "target_qps": 0
}

List AI Search endpoints Public Preview

GET /api/2.0/ai-search/{parent=workspaces/*}/endpoints

List AI Search endpoints in a workspace.

API scopes: ai-search

Parameters

parentstringRequiredpath: The Workspace that owns this collection of endpoints. Format: workspaces/{workspace_id}

page_sizeint32query: Best-effort upper bound on the number of results to return. Honored as an upper bound by the shim: page_size only narrows the legacy backend's response, never widens it, so the practical cap is min(page_size, legacy_fixed_page_size).

page_tokenstringquery: Page token from a previous response. If not provided, returns the first page.

Response

Returns a list of Endpoint objects.

View as Markdown

Response

{
  "endpoints": [
    {
      "name": "docs-endpoint",
      "creator": "john@example.com",
      "create_time": "2023-12-08T05:31:52.061Z",
      "update_time": "2023-12-08T05:31:52.061Z",
      "endpoint_type": "STORAGE_OPTIMIZED",
      "last_updated_user": "john@example.com",
      "id": "c56bf0a9-4929-4bd4-8bd5-d82ca62f9c76",
      "endpoint_status": {},
      "index_count": 0,
      "budget_policy_id": "string",
      "effective_budget_policy_id": "8b0444ff-8b60-48b0-9d31-e391f6126e0f",
      "custom_tags": [
        {}
      ],
      "throughput_info": {},
      "scaling_info": {},
      "usage_policy_id": "string",
      "replica_count": 0,
      "target_qps": 0
    }
  ],
  "next_page_token": "string"
}

Create an AI Search endpoint Public Preview

POST /api/2.0/ai-search/{parent=workspaces/*}/endpoints

Create a new AI Search endpoint.

API scopes: ai-search

Parameters

parentstringRequiredpath: The Workspace where this Endpoint will be created. Format: workspaces/{workspace_id}

endpoint_idstringquery: The user-supplied short name for the Endpoint, per AIP-133. The server composes the full Endpoint.name as {parent}/endpoints/{endpoint_id}. AIP-133 does not list endpoint_id as a fields-may-be-required entry, so we annotate it OPTIONAL on the wire; the server still rejects empty values with INVALID_PARAMETER_VALUE.

Request body

The Endpoint resource to create. Fields other than endpoint.name carry the desired configuration; endpoint.name is server-assigned from parent and endpoint_id.

namestringIDImmutable: Name of the AI Search endpoint. Server-assigned full resource path (workspaces/{workspace}/endpoints/{endpoint}) on output. On create, the user-supplied short name is conveyed via CreateEndpointRequest.endpoint_id; the server composes the full name and returns it on the response.
Example: docs-endpoint

endpoint_typestringRequiredImmutable

Type of endpoint. Required on create and immutable thereafter.

Values:

STORAGE_OPTIMIZED
STANDARD

budget_policy_idstring: The user-selected budget policy id for the endpoint.

custom_tagsarray of object

The custom tags assigned to the endpoint

Show child attributesHide child attributes

keystringRequired: Key field for an AI Search endpoint tag.

valuestring: [Optional] Value field for an AI Search endpoint tag.

usage_policy_idstring: The usage policy id applied to the endpoint.

replica_countint32: The client-supplied desired number of replicas for the endpoint, applied at create/update time. Mutually exclusive with target_qps.

target_qpsint32: Target QPS for the endpoint. Mutually exclusive with replica_count. Best-effort; the system does not guarantee this QPS will be achieved.

Response

Returns the Endpoint object.

View as Markdown

Request

{
  "name": "docs-endpoint",
  "endpoint_type": "STORAGE_OPTIMIZED",
  "budget_policy_id": "string",
  "custom_tags": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "usage_policy_id": "string",
  "replica_count": 0,
  "target_qps": 0
}

Response

{
  "name": "docs-endpoint",
  "creator": "john@example.com",
  "create_time": "2023-12-08T05:31:52.061Z",
  "update_time": "2023-12-08T05:31:52.061Z",
  "endpoint_type": "STORAGE_OPTIMIZED",
  "last_updated_user": "john@example.com",
  "id": "c56bf0a9-4929-4bd4-8bd5-d82ca62f9c76",
  "endpoint_status": {
    "state": "PROVISIONING",
    "message": "string"
  },
  "index_count": 0,
  "budget_policy_id": "string",
  "effective_budget_policy_id": "8b0444ff-8b60-48b0-9d31-e391f6126e0f",
  "custom_tags": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "throughput_info": {
    "requested_concurrency": 10,
    "current_concurrency": 8,
    "current_concurrency_utilization_percentage": 75.5,
    "minimal_concurrency_allowed": 2,
    "maximum_concurrency_allowed": 140,
    "change_request_state": "CHANGE_SUCCESS",
    "change_request_message": "Throughput successfully adjusted to 10 vCPUs",
    "requested_num_replicas": 2,
    "current_num_replicas": 1
  },
  "scaling_info": {
    "state": "SCALING_CHANGE_APPLIED",
    "requested_target_qps": 500,
    "estimated_completion_time": "2026-10-04T18:00:00Z",
    "phase": "INITIALIZING_INDEX",
    "index_initialization_percentage": 40,
    "delayed_reason": "CAPACITY_UNAVAILABLE",
    "target_qps_change_allowed_after_time": "2026-10-04T18:00:00Z"
  },
  "usage_policy_id": "string",
  "replica_count": 0,
  "target_qps": 0
}

Update an AI Search endpoint Public Preview

PATCH /api/2.0/ai-search/{name=workspaces/*/endpoints/*}

Update an existing AI Search endpoint. Multi-bucket masks are supported and dispatched in deterministic bucket order: budget policy, custom tags, throughput, scaling/replicas, then metrics export. Per-bucket dispatch is not atomic across buckets — if a later bucket fails, earlier buckets may already have been applied.

API scopes: ai-search

Parameters

namestringRequiredIDImmutablepath: Name of the AI Search endpoint. Server-assigned full resource path (workspaces/{workspace}/endpoints/{endpoint}) on output. On create, the user-supplied short name is conveyed via CreateEndpointRequest.endpoint_id; the server composes the full name and returns it on the response.
Example: docs-endpoint

update_maskstringRequiredquery: The list of fields to update.

Request body

The Endpoint resource to update. endpoint.name carries the full resource path.

endpoint_typestringRequiredImmutable

Type of endpoint. Required on create and immutable thereafter.

Values:

STORAGE_OPTIMIZED
STANDARD

budget_policy_idstring: The user-selected budget policy id for the endpoint.

custom_tagsarray of object

The custom tags assigned to the endpoint

Show child attributesHide child attributes

keystringRequired: Key field for an AI Search endpoint tag.

valuestring: [Optional] Value field for an AI Search endpoint tag.

usage_policy_idstring: The usage policy id applied to the endpoint.

replica_countint32: The client-supplied desired number of replicas for the endpoint, applied at create/update time. Mutually exclusive with target_qps.

target_qpsint32: Target QPS for the endpoint. Mutually exclusive with replica_count. Best-effort; the system does not guarantee this QPS will be achieved.

Response

Returns the Endpoint object.

View as Markdown

Request

{
  "endpoint_type": "STORAGE_OPTIMIZED",
  "budget_policy_id": "string",
  "custom_tags": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "usage_policy_id": "string",
  "replica_count": 0,
  "target_qps": 0
}

Response

{
  "name": "docs-endpoint",
  "creator": "john@example.com",
  "create_time": "2023-12-08T05:31:52.061Z",
  "update_time": "2023-12-08T05:31:52.061Z",
  "endpoint_type": "STORAGE_OPTIMIZED",
  "last_updated_user": "john@example.com",
  "id": "c56bf0a9-4929-4bd4-8bd5-d82ca62f9c76",
  "endpoint_status": {
    "state": "PROVISIONING",
    "message": "string"
  },
  "index_count": 0,
  "budget_policy_id": "string",
  "effective_budget_policy_id": "8b0444ff-8b60-48b0-9d31-e391f6126e0f",
  "custom_tags": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "throughput_info": {
    "requested_concurrency": 10,
    "current_concurrency": 8,
    "current_concurrency_utilization_percentage": 75.5,
    "minimal_concurrency_allowed": 2,
    "maximum_concurrency_allowed": 140,
    "change_request_state": "CHANGE_SUCCESS",
    "change_request_message": "Throughput successfully adjusted to 10 vCPUs",
    "requested_num_replicas": 2,
    "current_num_replicas": 1
  },
  "scaling_info": {
    "state": "SCALING_CHANGE_APPLIED",
    "requested_target_qps": 500,
    "estimated_completion_time": "2026-10-04T18:00:00Z",
    "phase": "INITIALIZING_INDEX",
    "index_initialization_percentage": 40,
    "delayed_reason": "CAPACITY_UNAVAILABLE",
    "target_qps_change_allowed_after_time": "2026-10-04T18:00:00Z"
  },
  "usage_policy_id": "string",
  "replica_count": 0,
  "target_qps": 0
}

Delete an AI Search endpoint Public Preview

DELETE /api/2.0/ai-search/{name=workspaces/*/endpoints/*}

Delete an AI Search endpoint.

API scopes: ai-search

Parameters

namestringRequiredpath: Full resource name of the endpoint to delete. Format: workspaces/{workspace_id}/endpoints/{endpoint_id}

Endpoint object​

Get an AI Search endpoint Public Preview​

Parameters​

Response​

List AI Search endpoints Public Preview​

Parameters​

Response​

Create an AI Search endpoint Public Preview​

Parameters​

Request body​

Response​

Update an AI Search endpoint Public Preview​

Parameters​

Request body​

Response​

Delete an AI Search endpoint Public Preview​

Parameters​

Endpoint object

Get an AI Search endpoint Public Preview

Parameters

Response

List AI Search endpoints Public Preview

Parameters

Response

Create an AI Search endpoint Public Preview

Parameters

Request body

Response

Update an AI Search endpoint Public Preview

Parameters

Request body

Response

Delete an AI Search endpoint Public Preview

Parameters