--- title: "POST /v1/projects/{projectsId}/locations/{locationsId}:generateLossClusters" method: POST path: "/v1/projects/{projectsId}/locations/{locationsId}:generateLossClusters" tags: ["projects"] --- # POST /v1/projects/{projectsId}/locations/{locationsId}:generateLossClusters `POST /v1/projects/{projectsId}/locations/{locationsId}:generateLossClusters` ## Request - Base URL: `https://aiplatform.googleapis.com` - URL: `https://aiplatform.googleapis.com/v1/projects/{projectsId}/locations/{locationsId}:generateLossClusters` - Auth: OAuth 2 and OAuth 2 - Implicit: `https://accounts.google.com/o/oauth2/auth` - Scopes: `https://www.googleapis.com/auth/cloud-platform` - Authorization code: `https://accounts.google.com/o/oauth2/auth` - Token URL: `https://accounts.google.com/o/oauth2/token` scopes: `https://www.googleapis.com/auth/cloud-platform` Generates loss clusters from evaluation results. This is a statelss API method that would not modify the EvaluationSet resource. ## Path parameters - `projectsId` string, required - `locationsId` string, required ## Request body - GoogleCloudAiplatformV1GenerateLossClustersRequest: Request message for EvaluationAnalyticsService.GenerateLossClusters. - `configs` GoogleCloudAiplatformV1LossAnalysisConfig[]: Required. Configuration for the analysis algorithm. Analysis for multiple metrics and multiple candidates could be specified. - `candidate` string: Required. The candidate model/agent to analyze (e.g., "gemini-3.0-pro"). This targets the specific CandidateResult within the EvaluationResult. - `metric` string: Required. The metric to analyze (e.g., "tool_use_quality"). This filters the EvaluationItems in the EvalSet to only those where EvaluationResult.metric matches this value. - `evaluationSet` string: Reference to a persisted EvaluationSet. The service will read items from this set. - `inlineResults` GoogleCloudAiplatformV1GenerateLossClustersRequestEvaluationResultList: A wrapper to allow providing a list of items inline. - `evaluationResults` GoogleCloudAiplatformV1EvaluationResult[]: Required. The list of evaluation results to analyze. - `candidateResults` GoogleCloudAiplatformV1CandidateResult[]: Optional. The results for the metric. - `additionalResults` unknown - `candidate` string: Required. The candidate that is being evaluated. The value is the same as the candidate name in the EvaluationRequest. - `error` GoogleRpcStatus: The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors). - `code` integer: The status code, which should be an enum value of google.rpc.Code. - `details` object[]: A list of messages that carry the error details. There is a common set of message types for APIs to use. - `message` string: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client. - `explanation` string: Optional. The explanation for the metric. - `metric` string: Required. The metric that was evaluated. - `rubricVerdicts` GoogleCloudAiplatformV1RubricVerdict[]: Optional. The rubric verdicts for the metric. - `evaluatedRubric` GoogleCloudAiplatformV1Rubric: Message representing a single testable criterion for evaluation. One input prompt could have multiple rubrics. - `content` GoogleCloudAiplatformV1RubricContent: Content of the rubric, defining the testable criteria. - … - `importance` 'IMPORTANCE_UNSPECIFIED' | 'HIGH' | 'MEDIUM' | 'LOW': Optional. The relative importance of this rubric. - `rubricId` string: Unique identifier for the rubric. This ID is used to refer to this rubric, e.g., in RubricVerdict. - `type` string: Optional. A type designator for the rubric, which can inform how it's evaluated or interpreted by systems or users. It's recommended to use consistent, well-defined, upper snake_case strings. Examples: "SUMMARIZATION_QUALITY", "SAFETY_HARMFUL_CONTENT", "INSTRUCTION_ADHERENCE". - `reasoning` string: Optional. Human-readable reasoning or explanation for the verdict. This can include specific examples or details from the evaluated content that justify the given verdict. - `verdict` boolean: Required. Outcome of the evaluation against the rubric, represented as a boolean. `true` indicates a "Pass", `false` indicates a "Fail". - `score` number, float: Optional. The score for the metric. - `evaluationRequest` string: Required. The request item that was evaluated. Format: projects/{project}/locations/{location}/evaluationItems/{evaluation_item} - `evaluationRun` string: Required. The evaluation run that was used to generate the result. Format: projects/{project}/locations/{location}/evaluationRuns/{evaluation_run} - `metadata` unknown - `metric` string: Required. The metric that was evaluated. - `request` GoogleCloudAiplatformV1EvaluationRequest: A single evaluation request supporting input for both single-turn model generation and multi-turn agent execution traces. Valid input modes: 1. Inference Mode: `prompt` is set (containing text or AgentData context). 2. Offline Eval Mode: `prompt` is unset, and `candidate_responses` contains `agent_data` (the completed execution trace). Validation Rule: Either `prompt` must be set, OR at least one of the `candidate_responses` must contain `agent_data`. Metrics receive each candidate as an `EvaluationInstance`, whose fields are the names metrics can reference: `prompt` -> `prompt`, the candidate -> `response` (or `agent_eval_data` for `agent_data`), `golden_response` -> `reference`, `rubrics` -> `rubric_groups`, and `prompt.prompt_template_data.values` and `extra_context` -> `other_data`. - `candidateResponses` GoogleCloudAiplatformV1CandidateResponse[]: Optional. Responses from model under test and other baseline models for comparison. - `agentData` GoogleCloudAiplatformV1AgentData: Represents data specific to multi-turn agent evaluations. - `agents` object: Optional. A map containing the static configurations for each agent in the system. Key: agent_id (matches the `author` field in events). Value: The static configuration of the agent. - `turns` GoogleCloudAiplatformV1ConversationTurn[]: Optional. A chronological list of conversation turns. Each turn represents a logical execution cycle (e.g., User Input -> Agent Response). - … - `candidate` string: Required. The name of the candidate that produced the response. - `error` GoogleRpcStatus: The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors). - `code` integer: The status code, which should be an enum value of google.rpc.Code. - `details` object[]: A list of messages that carry the error details. There is a common set of message types for APIs to use. - … - `message` string: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client. - `text` string: Text response. - `value` unknown - `goldenResponse` GoogleCloudAiplatformV1CandidateResponse: Responses from model or agent. - `agentData` GoogleCloudAiplatformV1AgentData: Represents data specific to multi-turn agent evaluations. - `agents` object: Optional. A map containing the static configurations for each agent in the system. Key: agent_id (matches the `author` field in events). Value: The static configuration of the agent. - `turns` GoogleCloudAiplatformV1ConversationTurn[]: Optional. A chronological list of conversation turns. Each turn represents a logical execution cycle (e.g., User Input -> Agent Response). - … - `candidate` string: Required. The name of the candidate that produced the response. - `error` GoogleRpcStatus: The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors). - `code` integer: The status code, which should be an enum value of google.rpc.Code. - `details` object[]: A list of messages that carry the error details. There is a common set of message types for APIs to use. - … - `message` string: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client. - `text` string: Text response. - `value` unknown - `prompt` GoogleCloudAiplatformV1EvaluationPrompt: Prompt to be evaluated. This can represent a single-turn prompt or a multi-turn conversation for agent evaluations. - `agentData` GoogleCloudAiplatformV1AgentData: Represents data specific to multi-turn agent evaluations. - `agents` object: Optional. A map containing the static configurations for each agent in the system. Key: agent_id (matches the `author` field in events). Value: The static configuration of the agent. - `turns` GoogleCloudAiplatformV1ConversationTurn[]: Optional. A chronological list of conversation turns. Each turn represents a logical execution cycle (e.g., User Input -> Agent Response). - … - `promptTemplateData` GoogleCloudAiplatformV1EvaluationPromptPromptTemplateData: Message to hold a prompt template and the values to populate the template. - `values` object: The values for fields in the prompt template. - `text` string: Text prompt. - `userScenario` GoogleCloudAiplatformV1EvaluationPromptUserScenario: User scenario to help simulate multi-turn agent running results. - `conversationPlan` string: Required. The plan for the conversation, used to drive the multi-turn agent run and generate the simulated agent evaluation dataset. - `startingPrompt` string: Required. The prompt that starts the conversation between the simulated user and the agent under test. - `value` unknown - `rubrics` object: Optional. Named groups of rubrics associated with this prompt. The key is a user-defined name for the rubric group. ## Response `200` Successful response - GoogleLongrunningOperation: This resource represents a long-running operation that is the result of a network API call. - `done` boolean: If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available. - `error` GoogleRpcStatus: The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors). - `code` integer: The status code, which should be an enum value of google.rpc.Code. - `details` object[]: A list of messages that carry the error details. There is a common set of message types for APIs to use. - `message` string: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client. - `metadata` object: Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata. Any method that returns a long-running operation should document the metadata type, if any. - `name` string: The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the `name` should be a resource name ending with `operations/{unique_id}`. - `response` object: The normal, successful response of the operation. If the original method returns no data on success, such as `Delete`, the response is `google.protobuf.Empty`. If the original method is standard `Get`/`Create`/`Update`, the response should be the resource. For other methods, the response should have the type `XxxResponse`, where `Xxx` is the original method name. For example, if the original method name is `TakeSnapshot()`, the inferred response type is `TakeSnapshotResponse`. --- [API](https://skmtc.dev/google/apis/aiplatform.md) - [All operations](https://skmtc.dev/google/apis/aiplatform/llms.txt) - [OpenAPI document](https://skmtc.dev/google/apis/aiplatform/revisions/3aca3b348f0c?raw)