--- title: "Create Session" method: POST path: "/apps/{app_name}/users/{user_id}/sessions" --- # Create Session `POST /apps/{app_name}/users/{user_id}/sessions` ## Path parameters - `app_name` string, required - `user_id` string, required ## Request body - CreateSessionRequest - `sessionId` string, nullable — The ID of the session to create. If not provided, a random session ID will be generated. - `state` object, nullable — The initial state of the session. - `events` EventInput[], nullable — A list of events to initialize the session with. - `modelVersion` string, nullable - `content` Content — Contains the multi-part content of a message. - `parts` Part[], nullable — List of parts that constitute a single message. Each part may have a different IANA MIME type. - `mediaResolution` PartMediaResolution — Media resolution for the input media. - `level` 'MEDIA_RESOLUTION_UNSPECIFIED' | 'MEDIA_RESOLUTION_LOW' | 'MEDIA_RESOLUTION_MEDIUM' | 'MEDIA_RESOLUTION_HIGH' | 'MEDIA_RESOLUTION_ULTRA_HIGH' — The tokenization quality used for given media. - `numTokens` integer, nullable — Specifies the required sequence length for media tokenization. - `codeExecutionResult` CodeExecutionResult — Result of executing the ExecutableCode. Generated only when the `CodeExecution` tool is used. - `outcome` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_OK' | 'OUTCOME_FAILED' | 'OUTCOME_DEADLINE_EXCEEDED' — Outcome of the code execution. - `output` string, nullable — Optional. Contains stdout when code execution is successful, stderr or other description otherwise. - `id` string, nullable — Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id. This field is not supported in Vertex AI. - `executableCode` ExecutableCode — Code generated by the model that is meant to be executed, and the result returned to the model. Generated when using the `CodeExecution` tool, in which the code will be automatically executed, and a corresponding CodeExecutionResult will also be generated. - `code` string, nullable — Required. The code to be executed. - `language` 'LANGUAGE_UNSPECIFIED' | 'PYTHON' — Programming language of the `code`. - `id` string, nullable — Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`. This field is not supported in Vertex AI. - `fileData` FileData — URI-based data. A FileData message contains a URI pointing to data of a specific media type. It is used to represent images, audio, and video stored in Google Cloud Storage. - `displayName` string, nullable — Optional. The display name of the file. Used to provide a label or filename to distinguish files. This field is only returned in `PromptMessage` for prompt management. It is used in the Gemini calls only when server side tools (`code_execution`, `google_search`, and `url_context`) are enabled. This field is not supported in Gemini API. - `fileUri` string, nullable — Required. The URI of the file in Google Cloud Storage. - `mimeType` string, nullable — Required. The IANA standard MIME type of the source data. - `functionCall` FunctionCall — A predicted FunctionCall returned from the model that contains a string representing the FunctionDeclaration.name and a structured JSON object containing the parameters and their values. - `id` string, nullable — Optional. The unique id of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`. - `args` object, nullable — Optional. The function parameters and values in JSON object format. See FunctionDeclaration.parameters for parameter details. - `name` string, nullable — Optional. The name of the function to call. Matches FunctionDeclaration.name. - `partialArgs` PartialArg[], nullable — Optional. The partial argument value of the function call. If provided, represents the arguments/fields that are streamed incrementally. This field is not supported in Gemini API. - `boolValue` boolean, nullable — Optional. Represents a boolean value. - `jsonPath` string, nullable — Required. A JSON Path (RFC 9535) to the argument being streamed. https://datatracker.ietf.org/doc/html/rfc9535. e.g. "$.foo.bar[0].data". - `nullValue` 'NULL_VALUE', nullable — Optional. Represents a null value. - `numberValue` number, nullable — Optional. Represents a double value. - `stringValue` string, nullable — Optional. Represents a string value. - `willContinue` boolean, nullable — Optional. Whether this is not the last part of the same json_path. If true, another PartialArg message for the current json_path is expected to follow. - `willContinue` boolean, nullable — Optional. Whether this is the last part of the FunctionCall. If true, another partial message for the current FunctionCall is expected to follow. This field is not supported in Gemini API. - `functionResponse` FunctionResponse — The result output from a FunctionCall that contains a string representing the FunctionDeclaration.name and a structured JSON object containing any output from the function is used as context to the model. This should contain the result of a `FunctionCall` made based on model prediction. - `willContinue` boolean, nullable — Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`. This field is not supported in Vertex AI. - `scheduling` 'SCHEDULING_UNSPECIFIED' | 'SILENT' | 'WHEN_IDLE' | 'INTERRUPT' — Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE. - `parts` FunctionResponsePart[], nullable — Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types. - `inlineData` FunctionResponseBlob — Raw media bytes for function response. Text should not be sent as raw bytes, use the 'text' field. - … - `fileData` FunctionResponseFileData — URI based data for function response. This data type is not supported in Gemini API. - … - `id` string, nullable — Optional. The id of the function call this response is for. Populated by the client to match the corresponding function call `id`. - `name` string, nullable — Required. The name of the function to call. Matches FunctionDeclaration.name and FunctionCall.name. - `response` object, nullable — Required. The function response in JSON object format. Use "output" key to specify function output and "error" key to specify error details (if any). If "output" and "error" keys are not specified, then whole "response" is treated as function output. - `inlineData` Blob — A content blob. A Blob contains data of a specific media type. It is used to represent images, audio, and video. - `data` string, binary, nullable — Required. The raw bytes of the data. - `displayName` string, nullable — Optional. The display name of the blob. Used to provide a label or filename to distinguish blobs. This field is only returned in `PromptMessage` for prompt management. It is used in the Gemini calls only when server-side tools (`code_execution`, `google_search`, and `url_context`) are enabled. This field is not supported in Gemini API. - `mimeType` string, nullable — Required. The IANA standard MIME type of the source data. - `text` string, nullable — Optional. The text content of the part. When sent from the VSCode Gemini Code Assist extension, references to @mentioned items will be converted to markdown boldface text. For example `@my-repo` will be converted to and sent as `**my-repo**` by the IDE agent. - `thought` boolean, nullable — Optional. Indicates whether the `part` represents the model's thought process or reasoning. - `thoughtSignature` string, binary, nullable — Optional. An opaque signature for the thought so it can be reused in subsequent requests. - `videoMetadata` VideoMetadata — Provides metadata for a video, including the start and end offsets for clipping and the frame rate. - `endOffset` string, nullable — Optional. The end offset of the video. - `fps` number, nullable — Optional. The frame rate of the video sent to the model. If not specified, the default value is 1.0. The valid range is (0.0, 24.0]. - `startOffset` string, nullable — Optional. The start offset of the video. - `toolCall` ToolCall — A predicted server-side `ToolCall` returned from the model. This message contains information about a tool that the model wants to invoke. The client is NOT expected to execute this `ToolCall`. Instead, the client should pass this `ToolCall` back to the API in a subsequent turn within a `Content` message, along with the corresponding `ToolResponse`. - `id` string, nullable — Unique identifier of the tool call. The server returns the tool response with the matching `id`. - `toolType` 'TOOL_TYPE_UNSPECIFIED' | 'GOOGLE_SEARCH_WEB' | 'GOOGLE_SEARCH_IMAGE' | 'URL_CONTEXT' | 'GOOGLE_MAPS' | 'FILE_SEARCH' — The type of tool in the function call. - `args` object, nullable — The tool call arguments. Example: {"arg1": "value1", "arg2": "value2"}. - `toolResponse` ToolResponse — The output from a server-side `ToolCall` execution. This message contains the results of a tool invocation that was initiated by a `ToolCall` from the model. The client should pass this `ToolResponse` back to the API in a subsequent turn within a `Content` message, along with the corresponding `ToolCall`. - `id` string, nullable — The identifier of the tool call this response is for. - `toolType` 'TOOL_TYPE_UNSPECIFIED' | 'GOOGLE_SEARCH_WEB' | 'GOOGLE_SEARCH_IMAGE' | 'URL_CONTEXT' | 'GOOGLE_MAPS' | 'FILE_SEARCH' — The type of tool in the function call. - `response` object, nullable — The tool response. - `partMetadata` object, nullable — Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams. This field is not supported in Vertex AI. - `audioTranscription` Transcription — Audio transcription in Server Content. - `text` string, nullable — Optional. Transcription text. - `finished` boolean, nullable — Optional. The bool indicates the end of the transcription. - `languageCode` string, nullable — The BCP-47 language code of the transcription. - `speakerLabel` string, nullable — A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). - `words` WordInfo[], nullable — Detailed word-level transcriptions and timing details. - `word` string, nullable — Transcript of the word. - `startOffset` string, nullable — Start offset in time of the word relative to the start of the audio. - `endOffset` string, nullable — End offset in time of the word relative to the start of the audio. - `role` string, nullable — Optional. The producer of the content. Must be either 'user' or 'model'. If not set, the service will default to 'user'. - `groundingMetadata` GroundingMetadata — Information for various kinds of grounding. - `imageSearchQueries` string[], nullable — Optional. The image search queries that were used to generate the content. This field is populated only when the grounding source is Google Search with the Image Search search_type enabled. - `groundingChunks` GroundingChunk[], nullable — A list of supporting references retrieved from the grounding source. This field is populated when the grounding source is Google Search, Vertex AI Search, or Google Maps. - `image` GroundingChunkImage — An `Image` chunk is a piece of evidence that comes from an image search result. It contains the URI of the image search result and the URI of the image. This is used to provide the user with a link to the source of the information. - `sourceUri` string, nullable — The URI of the image search result page. - `imageUri` string, nullable — The URI of the image. - `title` string, nullable — The title of the image search result page. - `domain` string, nullable — The domain of the image search result page. - `maps` GroundingChunkMaps — A `Maps` chunk is a piece of evidence that comes from Google Maps. It contains information about a place, such as its name, address, and reviews. This is used to provide the user with rich, location-based information. - `placeAnswerSources` GroundingChunkMapsPlaceAnswerSources — The sources that were used to generate the place answer. This includes review snippets and photos that were used to generate the answer, as well as URIs to flag content. - `reviewSnippet` GroundingChunkMapsPlaceAnswerSourcesReviewSnippet[], nullable — Snippets of reviews that were used to generate the answer. - … - `flagContentUri` string, nullable — A link where users can flag a problem with the generated answer. - `reviewSnippets` GroundingChunkMapsPlaceAnswerSourcesReviewSnippet[], nullable — Snippets of reviews that were used to generate the answer. - … - `placeId` string, nullable — This Place's resource name, in `places/{place_id}` format. This can be used to look up the place in the Google Maps API. - `text` string, nullable — The text of the place answer. - `title` string, nullable — The title of the place. - `uri` string, nullable — The URI of the place. - `route` GroundingChunkMapsRoute — Route information from Google Maps. This data type is not supported in Gemini API. - `distanceMeters` integer, nullable — The total distance of the route, in meters. - `duration` string, nullable — The total duration of the route. - `encodedPolyline` string, nullable — An encoded polyline of the route. See https://developers.google.com/maps/documentation/utilities/polylinealgorithm - `retrievedContext` GroundingChunkRetrievedContext — Context retrieved from a data source to ground the model's response. This is used when a retrieval tool fetches information from a user-provided corpus or a public dataset. - `documentName` string, nullable — Output only. The full resource name of the referenced Vertex AI Search document. This is used to identify the specific document that was retrieved. The format is `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}/branches/{branch}/documents/{document}`. This field is not supported in Gemini API. - `ragChunk` RagChunk — A RagChunk includes the content of a chunk of a RagFile, and associated metadata. This data type is not supported in Gemini API. - `pageSpan` RagChunkPageSpan — Represents where the chunk starts and ends in the document. This data type is not supported in Gemini API. - … - `text` string, nullable — The content of the chunk. - `chunkId` string, nullable — The ID of the chunk. - `fileId` string, nullable — The ID of the file that the chunk belongs to. - `text` string, nullable — The content of the retrieved data source. - `title` string, nullable — The title of the retrieved data source. - `uri` string, nullable — The URI of the retrieved data source. - `customMetadata` GroundingChunkCustomMetadata[], nullable — Optional. User-provided metadata about the retrieved context. This field is not supported in Vertex AI. - `key` string, nullable — The key of the metadata. - `numericValue` number, nullable — Optional. The numeric value of the metadata. The expected range for this value depends on the specific `key` used. - `stringListValue` GroundingChunkStringList — A list of string values. This data type is not supported in Vertex AI. - … - `stringValue` string, nullable — Optional. The string value of the metadata. - `fileSearchStore` string, nullable — Optional. Name of the `FileSearchStore` containing the document. Example: `fileSearchStores/123`. This field is not supported in Vertex AI. - `pageNumber` integer, nullable — Optional. Page number of the retrieved context, if applicable. This field is not supported in Vertex AI. - `mediaId` string, nullable — Optional. The media blob resource name for multimodal file search results. Format: fileSearchStores/{file_search_store_id}/media/{blob_id}. This field is not supported in Vertex AI. - `web` GroundingChunkWeb — A `Web` chunk is a piece of evidence that comes from a web page. It contains the URI of the web page, the title of the page, and the domain of the page. This is used to provide the user with a link to the source of the information. - `domain` string, nullable — The domain of the web page that contains the evidence. This can be used to filter out low-quality sources. This field is not supported in Gemini API. - `title` string, nullable — The title of the web page that contains the evidence. - `uri` string, nullable — The URI of the web page that contains the evidence. - `groundingSupports` GroundingSupport[], nullable — List of grounding support. - `confidenceScores` number[], nullable — Confidence score of the support references. Ranges from 0 to 1. 1 is the most confident. This list must have the same size as the grounding_chunk_indices. - `groundingChunkIndices` integer[], nullable — A list of indices (into 'grounding_chunk') specifying the citations associated with the claim. For instance [1,3,4] means that grounding_chunk[1], grounding_chunk[3], grounding_chunk[4] are the retrieved content attributed to the claim. - `segment` Segment — Segment of the content this support belongs to. - `startIndex` integer, nullable — Output only. Start index in the given Part, measured in bytes. Offset from the start of the Part, inclusive, starting at zero. - `endIndex` integer, nullable — Output only. End index in the given Part, measured in bytes. Offset from the start of the Part, exclusive, starting at zero. - `partIndex` integer, nullable — Output only. The index of a Part object within its parent Content object. - `text` string, nullable — Output only. The text corresponding to the segment from the response. - `renderedParts` integer[], nullable — Indices into the `rendered_parts` field of the `GroundingMetadata` message. These indices specify which rendered parts are associated with this support message. - `retrievalMetadata` RetrievalMetadata — Metadata returned to client when grounding is enabled. - `googleSearchDynamicRetrievalScore` number, nullable — Optional. Score indicating how likely information from google search could help answer the prompt. The score is in the range [0, 1], where 0 is the least likely and 1 is the most likely. This score is only populated when google search grounding and dynamic retrieval is enabled. It will be compared to the threshold to determine whether to trigger Google search. - `searchEntryPoint` SearchEntryPoint — The entry point used to search for grounding sources. - `renderedContent` string, nullable — Optional. Web content snippet that can be embedded in a web page or an app webview. - `sdkBlob` string, binary, nullable — Optional. JSON representing array of tuples. - `webSearchQueries` string[], nullable — Web search queries for the following-up web search. - `googleMapsWidgetContextToken` string, nullable — Optional. Output only. Deprecated: The Google Maps contextual widget behavior in Grounding with Google Maps is being deprecated; this field is planned for removal and will no longer be populated once removed. A token that can be used to render a Google Maps widget with the contextual data. This field is populated only when the grounding source is Google Maps. - `retrievalQueries` string[], nullable — Optional. The queries that were executed by the retrieval tools. This field is populated only when the grounding source is a retrieval tool, such as Vertex AI Search. This field is not supported in Gemini API. - `sourceFlaggingUris` GroundingMetadataSourceFlaggingUri[], nullable — Optional. Output only. A list of URIs that can be used to flag a place or review for inappropriate content. This field is populated only when the grounding source is Google Maps. This field is not supported in Gemini API. - `flagContentUri` string, nullable — The URI that can be used to flag the content. - `sourceId` string, nullable — The ID of the place or review. - `partial` boolean, nullable - `turnComplete` boolean, nullable - `turnCompleteReason` 'TURN_COMPLETE_REASON_UNSPECIFIED' | 'MALFORMED_FUNCTION_CALL' | 'RESPONSE_REJECTED' | 'NEED_MORE_INPUT' | 'PROHIBITED_INPUT_CONTENT' | 'IMAGE_PROHIBITED_INPUT_CONTENT' | 'INPUT_TEXT_CONTAIN_PROMINENT_PERSON_PROHIBITED' | 'INPUT_IMAGE_CELEBRITY' | 'INPUT_IMAGE_PHOTO_REALISTIC_CHILD_PROHIBITED' | 'INPUT_TEXT_NCII_PROHIBITED' | 'INPUT_OTHER' | 'INPUT_IP_PROHIBITED' | 'BLOCKLIST' | 'UNSAFE_PROMPT_FOR_IMAGE_GENERATION' | 'GENERATED_IMAGE_SAFETY' | 'GENERATED_CONTENT_SAFETY' | 'GENERATED_AUDIO_SAFETY' | 'GENERATED_VIDEO_SAFETY' | 'GENERATED_CONTENT_PROHIBITED' | 'GENERATED_CONTENT_BLOCKLIST' | 'GENERATED_IMAGE_PROHIBITED' | 'GENERATED_IMAGE_CELEBRITY' | 'GENERATED_IMAGE_PROMINENT_PEOPLE_DETECTED_BY_REWRITER' | 'GENERATED_IMAGE_IDENTIFIABLE_PEOPLE' | 'GENERATED_IMAGE_MINORS' | 'OUTPUT_IMAGE_IP_PROHIBITED' | 'GENERATED_OTHER' | 'MAX_REGENERATION_REACHED' — The reason why the turn is complete. - `finishReason` 'FINISH_REASON_UNSPECIFIED' | 'STOP' | 'MAX_TOKENS' | 'SAFETY' | 'RECITATION' | 'LANGUAGE' | 'OTHER' | 'BLOCKLIST' | 'PROHIBITED_CONTENT' | 'SPII' | 'MALFORMED_FUNCTION_CALL' | 'IMAGE_SAFETY' | 'UNEXPECTED_TOOL_CALL' | 'IMAGE_PROHIBITED_CONTENT' | 'NO_IMAGE' | 'IMAGE_RECITATION' | 'IMAGE_OTHER' — Output only. The reason why the model stopped generating tokens. If empty, the model has not stopped generating the tokens. - `errorCode` string, nullable - `errorMessage` string, nullable - `interrupted` boolean, nullable - `customMetadata` object, nullable - `usageMetadata` GenerateContentResponseUsageMetadata — Usage metadata about the content generation request and response. This message provides a detailed breakdown of token usage and other relevant metrics. This data type is not supported in Gemini API. - `cacheTokensDetails` ModalityTokenCount[], nullable — Output only. A detailed breakdown of the token count for each modality in the cached content. - `modality` 'MODALITY_UNSPECIFIED' | 'TEXT' | 'IMAGE' | 'VIDEO' | 'AUDIO' | 'DOCUMENT' — The modality that this token count applies to. - `tokenCount` integer, nullable — The number of tokens counted for this modality. - `cachedContentTokenCount` integer, nullable — Output only. The number of tokens in the cached content that was used for this request. - `candidatesTokenCount` integer, nullable — The total number of tokens in the generated candidates. - `candidatesTokensDetails` ModalityTokenCount[], nullable — Output only. A detailed breakdown of the token count for each modality in the generated candidates. - `modality` 'MODALITY_UNSPECIFIED' | 'TEXT' | 'IMAGE' | 'VIDEO' | 'AUDIO' | 'DOCUMENT' — The modality that this token count applies to. - `tokenCount` integer, nullable — The number of tokens counted for this modality. - `promptTokenCount` integer, nullable — The total number of tokens in the prompt. This includes any text, images, or other media provided in the request. When `cached_content` is set, this also includes the number of tokens in the cached content. - `promptTokensDetails` ModalityTokenCount[], nullable — Output only. A detailed breakdown of the token count for each modality in the prompt. - `modality` 'MODALITY_UNSPECIFIED' | 'TEXT' | 'IMAGE' | 'VIDEO' | 'AUDIO' | 'DOCUMENT' — The modality that this token count applies to. - `tokenCount` integer, nullable — The number of tokens counted for this modality. - `thoughtsTokenCount` integer, nullable — Output only. The number of tokens that were part of the model's generated "thoughts" output, if applicable. - `toolUsePromptTokenCount` integer, nullable — Output only. The number of tokens in the results from tool executions, which are provided back to the model as input, if applicable. - `toolUsePromptTokensDetails` ModalityTokenCount[], nullable — Output only. A detailed breakdown by modality of the token counts from the results of tool executions, which are provided back to the model as input. - `modality` 'MODALITY_UNSPECIFIED' | 'TEXT' | 'IMAGE' | 'VIDEO' | 'AUDIO' | 'DOCUMENT' — The modality that this token count applies to. - `tokenCount` integer, nullable — The number of tokens counted for this modality. - `totalTokenCount` integer, nullable — The total number of tokens for the entire request. This is the sum of `prompt_token_count`, `candidates_token_count`, `tool_use_prompt_token_count`, and `thoughts_token_count`. - `trafficType` 'TRAFFIC_TYPE_UNSPECIFIED' | 'ON_DEMAND' | 'ON_DEMAND_PRIORITY' | 'ON_DEMAND_FLEX' | 'PROVISIONED_THROUGHPUT' — Output only. The traffic type for this request. This enum is not supported in Gemini API. - `liveSessionResumptionUpdate` LiveServerSessionResumptionUpdate — Update of the session resumption state. Only sent if `session_resumption` was set in the connection config. - `newHandle` string, nullable — New handle that represents state that can be resumed. Empty if `resumable`=false. - `resumable` boolean, nullable — True if session can be resumed at this point. It might be not possible to resume session at some points. In that case we send update empty new_handle and resumable=false. Example of such case could be model executing function calls or just generating. Resuming session (using previous session token) in such state will result in some data loss. - `lastConsumedClientMessageIndex` integer, nullable — Index of last message sent by client that is included in state represented by this SessionResumptionToken. Only sent when `SessionResumptionConfig.transparent` is set. Presence of this index allows users to transparently reconnect and avoid issue of losing some part of realtime audio input/video. If client wishes to temporarily disconnect (for example as result of receiving GoAway) they can do it without losing state by buffering messages sent since last `SessionResumptionTokenUpdate`. This field will enable them to limit buffering (avoid keeping all requests in RAM). Note: This should not be used for when resuming a session at some time later -- in those cases partial audio and video frames are likely not needed. - `liveSessionId` string, nullable - `goAway` LiveServerGoAway — Server will not be able to service client soon. - `timeLeft` string, nullable — The remaining time before the connection will be terminated as ABORTED. The minimal time returned here is specified differently together with the rate limits for a given model. - `voiceActivity` VoiceActivity — Voice activity signal. - `voiceActivityType` 'TYPE_UNSPECIFIED' | 'ACTIVITY_START' | 'ACTIVITY_END' — The type of the voice activity signal. - `audioOffset` string, nullable — The time voice activity detected in audio time, relative to the start of the audio stream. - `inputTranscription` Transcription — Audio transcription in Server Content. - `text` string, nullable — Optional. Transcription text. - `finished` boolean, nullable — Optional. The bool indicates the end of the transcription. - `languageCode` string, nullable — The BCP-47 language code of the transcription. - `speakerLabel` string, nullable — A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). - `words` WordInfo[], nullable — Detailed word-level transcriptions and timing details. - `word` string, nullable — Transcript of the word. - `startOffset` string, nullable — Start offset in time of the word relative to the start of the audio. - `endOffset` string, nullable — End offset in time of the word relative to the start of the audio. - `outputTranscription` Transcription — Audio transcription in Server Content. - `text` string, nullable — Optional. Transcription text. - `finished` boolean, nullable — Optional. The bool indicates the end of the transcription. - `languageCode` string, nullable — The BCP-47 language code of the transcription. - `speakerLabel` string, nullable — A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). - `words` WordInfo[], nullable — Detailed word-level transcriptions and timing details. - `word` string, nullable — Transcript of the word. - `startOffset` string, nullable — Start offset in time of the word relative to the start of the audio. - `endOffset` string, nullable — End offset in time of the word relative to the start of the audio. - `avgLogprobs` number, nullable - `logprobsResult` LogprobsResult — The log probabilities of the tokens generated by the model. This is useful for understanding the model's confidence in its predictions and for debugging. For example, you can use log probabilities to identify when the model is making a less confident prediction or to explore alternative responses that the model considered. A low log probability can also indicate that the model is "hallucinating" or generating factually incorrect information. - `chosenCandidates` LogprobsResultCandidate[], nullable — A list of the chosen candidate tokens at each decoding step. The length of this list is equal to the total number of decoding steps. Note that the chosen candidate might not be in `top_candidates`. - `logProbability` number, nullable — The log probability of this token. A higher value indicates that the model was more confident in this token. The log probability can be used to assess the relative likelihood of different tokens and to identify when the model is uncertain. - `token` string, nullable — The token's string representation. - `tokenId` integer, nullable — The token's numerical ID. While the `token` field provides the string representation of the token, the `token_id` is the numerical representation that the model uses internally. This can be useful for developers who want to build custom logic based on the model's vocabulary. - `topCandidates` LogprobsResultTopCandidates[], nullable — A list of the top candidate tokens at each decoding step. The length of this list is equal to the total number of decoding steps. - `candidates` LogprobsResultCandidate[], nullable — The list of candidate tokens, sorted by log probability in descending order. - `logProbability` number, nullable — The log probability of this token. A higher value indicates that the model was more confident in this token. The log probability can be used to assess the relative likelihood of different tokens and to identify when the model is uncertain. - `token` string, nullable — The token's string representation. - `tokenId` integer, nullable — The token's numerical ID. While the `token` field provides the string representation of the token, the `token_id` is the numerical representation that the model uses internally. This can be useful for developers who want to build custom logic based on the model's vocabulary. - `logProbabilitySum` number, nullable — Sum of log probabilities for all tokens. This field is not supported in Vertex AI. - `cacheMetadata` CacheMetadata — Metadata for context cache associated with LLM responses. This class stores cache identification, usage tracking, and lifecycle information for a particular cache instance. It can be in two states: 1. Active cache state: cache_name is set, all fields populated 2. Fingerprint-only state: cache_name is None, only fingerprint and contents_count are set for prefix matching Token counts (cached and total) are available in the LlmResponse.usage_metadata and should be accessed from there to avoid duplication. Attributes: cache_name: The full resource name of the cached content (e.g., 'projects/123/locations/us-central1/cachedContents/456'). None when no active cache exists (fingerprint-only state). expire_time: Unix timestamp when the cache expires. None when no active cache exists. fingerprint: Hash of cacheable contents (instruction + tools + contents). Always present for prefix matching. invocations_used: Number of invocations this cache has been used for. None when no active cache exists. contents_count: Number of contents. When active cache exists, this is the count of cached contents. When no active cache exists, this is the count of the cacheable content prefix used for fingerprinting. created_at: Unix timestamp when the cache was created. None when no active cache exists. - `cache_name` string, nullable — Full resource name of the cached content (None if no active cache) - `expire_time` number, nullable — Unix timestamp when cache expires (None if no active cache) - `fingerprint` string, required — Hash of cacheable contents used to detect changes - `invocations_used` integer, nullable — Number of invocations this cache has been used for (None if no active cache) - `contents_count` integer, required — Number of contents (cached contents when active cache exists, cacheable content prefix when no active cache) - `created_at` number, nullable — Unix timestamp when cache was created (None if no active cache) - `citationMetadata` CitationMetadata — Citation information when the model quotes another source. - `citations` Citation[], nullable — Contains citation information when the model directly quotes, at length, from another source. Can include traditional websites and code repositories. - `endIndex` integer, nullable — Output only. The end index of the citation in the content. - `license` string, nullable — Output only. The license of the source of the citation. - `publicationDate` GoogleTypeDate — Represents a whole or partial calendar date, such as a birthday. The time of day and time zone are either specified elsewhere or are insignificant. The date is relative to the Gregorian Calendar. This can represent one of the following: * A full date, with non-zero year, month, and day values. * A month and day, with a zero year (for example, an anniversary). * A year on its own, with a zero month and a zero day. * A year and month, with a zero day (for example, a credit card expiration date). Related types: * google.type.TimeOfDay * google.type.DateTime * google.protobuf.Timestamp. This data type is not supported in Gemini API. - `day` integer, nullable — Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant. - `month` integer, nullable — Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day. - `year` integer, nullable — Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year. - `startIndex` integer, nullable — Output only. The start index of the citation in the content. - `title` string, nullable — Output only. The title of the source of the citation. - `uri` string, nullable — Output only. The URI of the source of the citation. - `interactionId` string, nullable - `environmentId` string, nullable - `invocationId` string - `author` string - `actions` EventActionsInput — Represents the actions attached to an event. - `skipSummarization` boolean, nullable - `stateDelta` object - `artifactDelta` object - `transferToAgent` string, nullable - `escalate` boolean, nullable - `requestedAuthConfigs` object - `requestedToolConfirmations` object - `compaction` EventCompaction — The compaction of the events. - `startTimestamp` number, required - `endTimestamp` number, required - `compactedContent` Content, required — Contains the multi-part content of a message. - `parts` Part[], nullable — List of parts that constitute a single message. Each part may have a different IANA MIME type. - `mediaResolution` PartMediaResolution — Media resolution for the input media. - … - `codeExecutionResult` CodeExecutionResult — Result of executing the ExecutableCode. Generated only when the `CodeExecution` tool is used. - … - `executableCode` ExecutableCode — Code generated by the model that is meant to be executed, and the result returned to the model. Generated when using the `CodeExecution` tool, in which the code will be automatically executed, and a corresponding CodeExecutionResult will also be generated. - … - `fileData` FileData — URI-based data. A FileData message contains a URI pointing to data of a specific media type. It is used to represent images, audio, and video stored in Google Cloud Storage. - … - `functionCall` FunctionCall — A predicted FunctionCall returned from the model that contains a string representing the FunctionDeclaration.name and a structured JSON object containing the parameters and their values. - … - `functionResponse` FunctionResponse — The result output from a FunctionCall that contains a string representing the FunctionDeclaration.name and a structured JSON object containing any output from the function is used as context to the model. This should contain the result of a `FunctionCall` made based on model prediction. - … - `inlineData` Blob — A content blob. A Blob contains data of a specific media type. It is used to represent images, audio, and video. - … - `text` string, nullable — Optional. The text content of the part. When sent from the VSCode Gemini Code Assist extension, references to @mentioned items will be converted to markdown boldface text. For example `@my-repo` will be converted to and sent as `**my-repo**` by the IDE agent. - `thought` boolean, nullable — Optional. Indicates whether the `part` represents the model's thought process or reasoning. - `thoughtSignature` string, binary, nullable — Optional. An opaque signature for the thought so it can be reused in subsequent requests. - `videoMetadata` VideoMetadata — Provides metadata for a video, including the start and end offsets for clipping and the frame rate. - … - `toolCall` ToolCall — A predicted server-side `ToolCall` returned from the model. This message contains information about a tool that the model wants to invoke. The client is NOT expected to execute this `ToolCall`. Instead, the client should pass this `ToolCall` back to the API in a subsequent turn within a `Content` message, along with the corresponding `ToolResponse`. - … - `toolResponse` ToolResponse — The output from a server-side `ToolCall` execution. This message contains the results of a tool invocation that was initiated by a `ToolCall` from the model. The client should pass this `ToolResponse` back to the API in a subsequent turn within a `Content` message, along with the corresponding `ToolCall`. - … - `partMetadata` object, nullable — Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams. This field is not supported in Vertex AI. - `audioTranscription` Transcription — Audio transcription in Server Content. - … - `role` string, nullable — Optional. The producer of the content. Must be either 'user' or 'model'. If not set, the service will default to 'user'. - `endOfAgent` boolean, nullable - `agentState` object, nullable - `rewindBeforeInvocationId` string, nullable - `route` union - boolean - integer - string - union[] - union - boolean - integer - string - `renderUiWidgets` UiWidget[], nullable - `id` string, required - `provider` string, required - `payload` object - `setModelResponse` unknown - `output` unknown - `nodeInfo` NodeInfo — Workflow node metadata attached to an Event. - `path` string - `outputFor` string[], nullable - `messageAsOutput` boolean, nullable - `longRunningToolIds` string[], nullable - `branch` string, nullable - `isolationScope` string, nullable - `id` string - `timestamp` number ## Response `200` Successful Response - Session — Represents a series of interactions between a user and agents. - `id` string, required — Unique identifier of the session. - `appName` string, required — Application name that owns the session. - `userId` string, required — User ID that owns the session. - `state` object — Current persisted session state. - `events` EventOutput[] — Ordered event history for the session, including user, model, and tool events (e.g. user input, model response, function call/response). - `modelVersion` string, nullable - `content` Content — Contains the multi-part content of a message. - `parts` Part[], nullable — List of parts that constitute a single message. Each part may have a different IANA MIME type. - `mediaResolution` PartMediaResolution — Media resolution for the input media. - `level` 'MEDIA_RESOLUTION_UNSPECIFIED' | 'MEDIA_RESOLUTION_LOW' | 'MEDIA_RESOLUTION_MEDIUM' | 'MEDIA_RESOLUTION_HIGH' | 'MEDIA_RESOLUTION_ULTRA_HIGH' — The tokenization quality used for given media. - `numTokens` integer, nullable — Specifies the required sequence length for media tokenization. - `codeExecutionResult` CodeExecutionResult — Result of executing the ExecutableCode. Generated only when the `CodeExecution` tool is used. - `outcome` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_OK' | 'OUTCOME_FAILED' | 'OUTCOME_DEADLINE_EXCEEDED' — Outcome of the code execution. - `output` string, nullable — Optional. Contains stdout when code execution is successful, stderr or other description otherwise. - `id` string, nullable — Optional. The identifier of the `ExecutableCode` part this result is for. Only populated if the corresponding `ExecutableCode` has an id. This field is not supported in Vertex AI. - `executableCode` ExecutableCode — Code generated by the model that is meant to be executed, and the result returned to the model. Generated when using the `CodeExecution` tool, in which the code will be automatically executed, and a corresponding CodeExecutionResult will also be generated. - `code` string, nullable — Required. The code to be executed. - `language` 'LANGUAGE_UNSPECIFIED' | 'PYTHON' — Programming language of the `code`. - `id` string, nullable — Optional. Unique identifier of the `ExecutableCode` part. The server returns the `CodeExecutionResult` with the matching `id`. This field is not supported in Vertex AI. - `fileData` FileData — URI-based data. A FileData message contains a URI pointing to data of a specific media type. It is used to represent images, audio, and video stored in Google Cloud Storage. - `displayName` string, nullable — Optional. The display name of the file. Used to provide a label or filename to distinguish files. This field is only returned in `PromptMessage` for prompt management. It is used in the Gemini calls only when server side tools (`code_execution`, `google_search`, and `url_context`) are enabled. This field is not supported in Gemini API. - `fileUri` string, nullable — Required. The URI of the file in Google Cloud Storage. - `mimeType` string, nullable — Required. The IANA standard MIME type of the source data. - `functionCall` FunctionCall — A predicted FunctionCall returned from the model that contains a string representing the FunctionDeclaration.name and a structured JSON object containing the parameters and their values. - `id` string, nullable — Optional. The unique id of the function call. If populated, the client to execute the `function_call` and return the response with the matching `id`. - `args` object, nullable — Optional. The function parameters and values in JSON object format. See FunctionDeclaration.parameters for parameter details. - `name` string, nullable — Optional. The name of the function to call. Matches FunctionDeclaration.name. - `partialArgs` PartialArg[], nullable — Optional. The partial argument value of the function call. If provided, represents the arguments/fields that are streamed incrementally. This field is not supported in Gemini API. - `boolValue` boolean, nullable — Optional. Represents a boolean value. - `jsonPath` string, nullable — Required. A JSON Path (RFC 9535) to the argument being streamed. https://datatracker.ietf.org/doc/html/rfc9535. e.g. "$.foo.bar[0].data". - `nullValue` 'NULL_VALUE', nullable — Optional. Represents a null value. - `numberValue` number, nullable — Optional. Represents a double value. - `stringValue` string, nullable — Optional. Represents a string value. - `willContinue` boolean, nullable — Optional. Whether this is not the last part of the same json_path. If true, another PartialArg message for the current json_path is expected to follow. - `willContinue` boolean, nullable — Optional. Whether this is the last part of the FunctionCall. If true, another partial message for the current FunctionCall is expected to follow. This field is not supported in Gemini API. - `functionResponse` FunctionResponse — The result output from a FunctionCall that contains a string representing the FunctionDeclaration.name and a structured JSON object containing any output from the function is used as context to the model. This should contain the result of a `FunctionCall` made based on model prediction. - `willContinue` boolean, nullable — Optional. Signals that function call continues, and more responses will be returned, turning the function call into a generator. Is only applicable to NON_BLOCKING function calls, is ignored otherwise. If set to false, future responses will not be considered. It is allowed to return empty `response` with `will_continue=False` to signal that the function call is finished. This may still trigger the model generation. To avoid triggering the generation and finish the function call, additionally set `scheduling` to `SILENT`. This field is not supported in Vertex AI. - `scheduling` 'SCHEDULING_UNSPECIFIED' | 'SILENT' | 'WHEN_IDLE' | 'INTERRUPT' — Specifies how the response should be scheduled in the conversation. Only applicable to NON_BLOCKING function calls, is ignored otherwise. Defaults to WHEN_IDLE. - `parts` FunctionResponsePart[], nullable — Optional. Ordered `Parts` that constitute a function response. Parts may have different IANA MIME types. - `inlineData` FunctionResponseBlob — Raw media bytes for function response. Text should not be sent as raw bytes, use the 'text' field. - … - `fileData` FunctionResponseFileData — URI based data for function response. This data type is not supported in Gemini API. - … - `id` string, nullable — Optional. The id of the function call this response is for. Populated by the client to match the corresponding function call `id`. - `name` string, nullable — Required. The name of the function to call. Matches FunctionDeclaration.name and FunctionCall.name. - `response` object, nullable — Required. The function response in JSON object format. Use "output" key to specify function output and "error" key to specify error details (if any). If "output" and "error" keys are not specified, then whole "response" is treated as function output. - `inlineData` Blob — A content blob. A Blob contains data of a specific media type. It is used to represent images, audio, and video. - `data` string, binary, nullable — Required. The raw bytes of the data. - `displayName` string, nullable — Optional. The display name of the blob. Used to provide a label or filename to distinguish blobs. This field is only returned in `PromptMessage` for prompt management. It is used in the Gemini calls only when server-side tools (`code_execution`, `google_search`, and `url_context`) are enabled. This field is not supported in Gemini API. - `mimeType` string, nullable — Required. The IANA standard MIME type of the source data. - `text` string, nullable — Optional. The text content of the part. When sent from the VSCode Gemini Code Assist extension, references to @mentioned items will be converted to markdown boldface text. For example `@my-repo` will be converted to and sent as `**my-repo**` by the IDE agent. - `thought` boolean, nullable — Optional. Indicates whether the `part` represents the model's thought process or reasoning. - `thoughtSignature` string, binary, nullable — Optional. An opaque signature for the thought so it can be reused in subsequent requests. - `videoMetadata` VideoMetadata — Provides metadata for a video, including the start and end offsets for clipping and the frame rate. - `endOffset` string, nullable — Optional. The end offset of the video. - `fps` number, nullable — Optional. The frame rate of the video sent to the model. If not specified, the default value is 1.0. The valid range is (0.0, 24.0]. - `startOffset` string, nullable — Optional. The start offset of the video. - `toolCall` ToolCall — A predicted server-side `ToolCall` returned from the model. This message contains information about a tool that the model wants to invoke. The client is NOT expected to execute this `ToolCall`. Instead, the client should pass this `ToolCall` back to the API in a subsequent turn within a `Content` message, along with the corresponding `ToolResponse`. - `id` string, nullable — Unique identifier of the tool call. The server returns the tool response with the matching `id`. - `toolType` 'TOOL_TYPE_UNSPECIFIED' | 'GOOGLE_SEARCH_WEB' | 'GOOGLE_SEARCH_IMAGE' | 'URL_CONTEXT' | 'GOOGLE_MAPS' | 'FILE_SEARCH' — The type of tool in the function call. - `args` object, nullable — The tool call arguments. Example: {"arg1": "value1", "arg2": "value2"}. - `toolResponse` ToolResponse — The output from a server-side `ToolCall` execution. This message contains the results of a tool invocation that was initiated by a `ToolCall` from the model. The client should pass this `ToolResponse` back to the API in a subsequent turn within a `Content` message, along with the corresponding `ToolCall`. - `id` string, nullable — The identifier of the tool call this response is for. - `toolType` 'TOOL_TYPE_UNSPECIFIED' | 'GOOGLE_SEARCH_WEB' | 'GOOGLE_SEARCH_IMAGE' | 'URL_CONTEXT' | 'GOOGLE_MAPS' | 'FILE_SEARCH' — The type of tool in the function call. - `response` object, nullable — The tool response. - `partMetadata` object, nullable — Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams. This field is not supported in Vertex AI. - `audioTranscription` Transcription — Audio transcription in Server Content. - `text` string, nullable — Optional. Transcription text. - `finished` boolean, nullable — Optional. The bool indicates the end of the transcription. - `languageCode` string, nullable — The BCP-47 language code of the transcription. - `speakerLabel` string, nullable — A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). - `words` WordInfo[], nullable — Detailed word-level transcriptions and timing details. - `word` string, nullable — Transcript of the word. - `startOffset` string, nullable — Start offset in time of the word relative to the start of the audio. - `endOffset` string, nullable — End offset in time of the word relative to the start of the audio. - `role` string, nullable — Optional. The producer of the content. Must be either 'user' or 'model'. If not set, the service will default to 'user'. - `groundingMetadata` GroundingMetadata — Information for various kinds of grounding. - `imageSearchQueries` string[], nullable — Optional. The image search queries that were used to generate the content. This field is populated only when the grounding source is Google Search with the Image Search search_type enabled. - `groundingChunks` GroundingChunk[], nullable — A list of supporting references retrieved from the grounding source. This field is populated when the grounding source is Google Search, Vertex AI Search, or Google Maps. - `image` GroundingChunkImage — An `Image` chunk is a piece of evidence that comes from an image search result. It contains the URI of the image search result and the URI of the image. This is used to provide the user with a link to the source of the information. - `sourceUri` string, nullable — The URI of the image search result page. - `imageUri` string, nullable — The URI of the image. - `title` string, nullable — The title of the image search result page. - `domain` string, nullable — The domain of the image search result page. - `maps` GroundingChunkMaps — A `Maps` chunk is a piece of evidence that comes from Google Maps. It contains information about a place, such as its name, address, and reviews. This is used to provide the user with rich, location-based information. - `placeAnswerSources` GroundingChunkMapsPlaceAnswerSources — The sources that were used to generate the place answer. This includes review snippets and photos that were used to generate the answer, as well as URIs to flag content. - `reviewSnippet` GroundingChunkMapsPlaceAnswerSourcesReviewSnippet[], nullable — Snippets of reviews that were used to generate the answer. - … - `flagContentUri` string, nullable — A link where users can flag a problem with the generated answer. - `reviewSnippets` GroundingChunkMapsPlaceAnswerSourcesReviewSnippet[], nullable — Snippets of reviews that were used to generate the answer. - … - `placeId` string, nullable — This Place's resource name, in `places/{place_id}` format. This can be used to look up the place in the Google Maps API. - `text` string, nullable — The text of the place answer. - `title` string, nullable — The title of the place. - `uri` string, nullable — The URI of the place. - `route` GroundingChunkMapsRoute — Route information from Google Maps. This data type is not supported in Gemini API. - `distanceMeters` integer, nullable — The total distance of the route, in meters. - `duration` string, nullable — The total duration of the route. - `encodedPolyline` string, nullable — An encoded polyline of the route. See https://developers.google.com/maps/documentation/utilities/polylinealgorithm - `retrievedContext` GroundingChunkRetrievedContext — Context retrieved from a data source to ground the model's response. This is used when a retrieval tool fetches information from a user-provided corpus or a public dataset. - `documentName` string, nullable — Output only. The full resource name of the referenced Vertex AI Search document. This is used to identify the specific document that was retrieved. The format is `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}/branches/{branch}/documents/{document}`. This field is not supported in Gemini API. - `ragChunk` RagChunk — A RagChunk includes the content of a chunk of a RagFile, and associated metadata. This data type is not supported in Gemini API. - `pageSpan` RagChunkPageSpan — Represents where the chunk starts and ends in the document. This data type is not supported in Gemini API. - … - `text` string, nullable — The content of the chunk. - `chunkId` string, nullable — The ID of the chunk. - `fileId` string, nullable — The ID of the file that the chunk belongs to. - `text` string, nullable — The content of the retrieved data source. - `title` string, nullable — The title of the retrieved data source. - `uri` string, nullable — The URI of the retrieved data source. - `customMetadata` GroundingChunkCustomMetadata[], nullable — Optional. User-provided metadata about the retrieved context. This field is not supported in Vertex AI. - `key` string, nullable — The key of the metadata. - `numericValue` number, nullable — Optional. The numeric value of the metadata. The expected range for this value depends on the specific `key` used. - `stringListValue` GroundingChunkStringList — A list of string values. This data type is not supported in Vertex AI. - … - `stringValue` string, nullable — Optional. The string value of the metadata. - `fileSearchStore` string, nullable — Optional. Name of the `FileSearchStore` containing the document. Example: `fileSearchStores/123`. This field is not supported in Vertex AI. - `pageNumber` integer, nullable — Optional. Page number of the retrieved context, if applicable. This field is not supported in Vertex AI. - `mediaId` string, nullable — Optional. The media blob resource name for multimodal file search results. Format: fileSearchStores/{file_search_store_id}/media/{blob_id}. This field is not supported in Vertex AI. - `web` GroundingChunkWeb — A `Web` chunk is a piece of evidence that comes from a web page. It contains the URI of the web page, the title of the page, and the domain of the page. This is used to provide the user with a link to the source of the information. - `domain` string, nullable — The domain of the web page that contains the evidence. This can be used to filter out low-quality sources. This field is not supported in Gemini API. - `title` string, nullable — The title of the web page that contains the evidence. - `uri` string, nullable — The URI of the web page that contains the evidence. - `groundingSupports` GroundingSupport[], nullable — List of grounding support. - `confidenceScores` number[], nullable — Confidence score of the support references. Ranges from 0 to 1. 1 is the most confident. This list must have the same size as the grounding_chunk_indices. - `groundingChunkIndices` integer[], nullable — A list of indices (into 'grounding_chunk') specifying the citations associated with the claim. For instance [1,3,4] means that grounding_chunk[1], grounding_chunk[3], grounding_chunk[4] are the retrieved content attributed to the claim. - `segment` Segment — Segment of the content this support belongs to. - `startIndex` integer, nullable — Output only. Start index in the given Part, measured in bytes. Offset from the start of the Part, inclusive, starting at zero. - `endIndex` integer, nullable — Output only. End index in the given Part, measured in bytes. Offset from the start of the Part, exclusive, starting at zero. - `partIndex` integer, nullable — Output only. The index of a Part object within its parent Content object. - `text` string, nullable — Output only. The text corresponding to the segment from the response. - `renderedParts` integer[], nullable — Indices into the `rendered_parts` field of the `GroundingMetadata` message. These indices specify which rendered parts are associated with this support message. - `retrievalMetadata` RetrievalMetadata — Metadata returned to client when grounding is enabled. - `googleSearchDynamicRetrievalScore` number, nullable — Optional. Score indicating how likely information from google search could help answer the prompt. The score is in the range [0, 1], where 0 is the least likely and 1 is the most likely. This score is only populated when google search grounding and dynamic retrieval is enabled. It will be compared to the threshold to determine whether to trigger Google search. - `searchEntryPoint` SearchEntryPoint — The entry point used to search for grounding sources. - `renderedContent` string, nullable — Optional. Web content snippet that can be embedded in a web page or an app webview. - `sdkBlob` string, binary, nullable — Optional. JSON representing array of tuples. - `webSearchQueries` string[], nullable — Web search queries for the following-up web search. - `googleMapsWidgetContextToken` string, nullable — Optional. Output only. Deprecated: The Google Maps contextual widget behavior in Grounding with Google Maps is being deprecated; this field is planned for removal and will no longer be populated once removed. A token that can be used to render a Google Maps widget with the contextual data. This field is populated only when the grounding source is Google Maps. - `retrievalQueries` string[], nullable — Optional. The queries that were executed by the retrieval tools. This field is populated only when the grounding source is a retrieval tool, such as Vertex AI Search. This field is not supported in Gemini API. - `sourceFlaggingUris` GroundingMetadataSourceFlaggingUri[], nullable — Optional. Output only. A list of URIs that can be used to flag a place or review for inappropriate content. This field is populated only when the grounding source is Google Maps. This field is not supported in Gemini API. - `flagContentUri` string, nullable — The URI that can be used to flag the content. - `sourceId` string, nullable — The ID of the place or review. - `partial` boolean, nullable - `turnComplete` boolean, nullable - `turnCompleteReason` 'TURN_COMPLETE_REASON_UNSPECIFIED' | 'MALFORMED_FUNCTION_CALL' | 'RESPONSE_REJECTED' | 'NEED_MORE_INPUT' | 'PROHIBITED_INPUT_CONTENT' | 'IMAGE_PROHIBITED_INPUT_CONTENT' | 'INPUT_TEXT_CONTAIN_PROMINENT_PERSON_PROHIBITED' | 'INPUT_IMAGE_CELEBRITY' | 'INPUT_IMAGE_PHOTO_REALISTIC_CHILD_PROHIBITED' | 'INPUT_TEXT_NCII_PROHIBITED' | 'INPUT_OTHER' | 'INPUT_IP_PROHIBITED' | 'BLOCKLIST' | 'UNSAFE_PROMPT_FOR_IMAGE_GENERATION' | 'GENERATED_IMAGE_SAFETY' | 'GENERATED_CONTENT_SAFETY' | 'GENERATED_AUDIO_SAFETY' | 'GENERATED_VIDEO_SAFETY' | 'GENERATED_CONTENT_PROHIBITED' | 'GENERATED_CONTENT_BLOCKLIST' | 'GENERATED_IMAGE_PROHIBITED' | 'GENERATED_IMAGE_CELEBRITY' | 'GENERATED_IMAGE_PROMINENT_PEOPLE_DETECTED_BY_REWRITER' | 'GENERATED_IMAGE_IDENTIFIABLE_PEOPLE' | 'GENERATED_IMAGE_MINORS' | 'OUTPUT_IMAGE_IP_PROHIBITED' | 'GENERATED_OTHER' | 'MAX_REGENERATION_REACHED' — The reason why the turn is complete. - `finishReason` 'FINISH_REASON_UNSPECIFIED' | 'STOP' | 'MAX_TOKENS' | 'SAFETY' | 'RECITATION' | 'LANGUAGE' | 'OTHER' | 'BLOCKLIST' | 'PROHIBITED_CONTENT' | 'SPII' | 'MALFORMED_FUNCTION_CALL' | 'IMAGE_SAFETY' | 'UNEXPECTED_TOOL_CALL' | 'IMAGE_PROHIBITED_CONTENT' | 'NO_IMAGE' | 'IMAGE_RECITATION' | 'IMAGE_OTHER' — Output only. The reason why the model stopped generating tokens. If empty, the model has not stopped generating the tokens. - `errorCode` string, nullable - `errorMessage` string, nullable - `interrupted` boolean, nullable - `customMetadata` object, nullable - `usageMetadata` GenerateContentResponseUsageMetadata — Usage metadata about the content generation request and response. This message provides a detailed breakdown of token usage and other relevant metrics. This data type is not supported in Gemini API. - `cacheTokensDetails` ModalityTokenCount[], nullable — Output only. A detailed breakdown of the token count for each modality in the cached content. - `modality` 'MODALITY_UNSPECIFIED' | 'TEXT' | 'IMAGE' | 'VIDEO' | 'AUDIO' | 'DOCUMENT' — The modality that this token count applies to. - `tokenCount` integer, nullable — The number of tokens counted for this modality. - `cachedContentTokenCount` integer, nullable — Output only. The number of tokens in the cached content that was used for this request. - `candidatesTokenCount` integer, nullable — The total number of tokens in the generated candidates. - `candidatesTokensDetails` ModalityTokenCount[], nullable — Output only. A detailed breakdown of the token count for each modality in the generated candidates. - `modality` 'MODALITY_UNSPECIFIED' | 'TEXT' | 'IMAGE' | 'VIDEO' | 'AUDIO' | 'DOCUMENT' — The modality that this token count applies to. - `tokenCount` integer, nullable — The number of tokens counted for this modality. - `promptTokenCount` integer, nullable — The total number of tokens in the prompt. This includes any text, images, or other media provided in the request. When `cached_content` is set, this also includes the number of tokens in the cached content. - `promptTokensDetails` ModalityTokenCount[], nullable — Output only. A detailed breakdown of the token count for each modality in the prompt. - `modality` 'MODALITY_UNSPECIFIED' | 'TEXT' | 'IMAGE' | 'VIDEO' | 'AUDIO' | 'DOCUMENT' — The modality that this token count applies to. - `tokenCount` integer, nullable — The number of tokens counted for this modality. - `thoughtsTokenCount` integer, nullable — Output only. The number of tokens that were part of the model's generated "thoughts" output, if applicable. - `toolUsePromptTokenCount` integer, nullable — Output only. The number of tokens in the results from tool executions, which are provided back to the model as input, if applicable. - `toolUsePromptTokensDetails` ModalityTokenCount[], nullable — Output only. A detailed breakdown by modality of the token counts from the results of tool executions, which are provided back to the model as input. - `modality` 'MODALITY_UNSPECIFIED' | 'TEXT' | 'IMAGE' | 'VIDEO' | 'AUDIO' | 'DOCUMENT' — The modality that this token count applies to. - `tokenCount` integer, nullable — The number of tokens counted for this modality. - `totalTokenCount` integer, nullable — The total number of tokens for the entire request. This is the sum of `prompt_token_count`, `candidates_token_count`, `tool_use_prompt_token_count`, and `thoughts_token_count`. - `trafficType` 'TRAFFIC_TYPE_UNSPECIFIED' | 'ON_DEMAND' | 'ON_DEMAND_PRIORITY' | 'ON_DEMAND_FLEX' | 'PROVISIONED_THROUGHPUT' — Output only. The traffic type for this request. This enum is not supported in Gemini API. - `liveSessionResumptionUpdate` LiveServerSessionResumptionUpdate — Update of the session resumption state. Only sent if `session_resumption` was set in the connection config. - `newHandle` string, nullable — New handle that represents state that can be resumed. Empty if `resumable`=false. - `resumable` boolean, nullable — True if session can be resumed at this point. It might be not possible to resume session at some points. In that case we send update empty new_handle and resumable=false. Example of such case could be model executing function calls or just generating. Resuming session (using previous session token) in such state will result in some data loss. - `lastConsumedClientMessageIndex` integer, nullable — Index of last message sent by client that is included in state represented by this SessionResumptionToken. Only sent when `SessionResumptionConfig.transparent` is set. Presence of this index allows users to transparently reconnect and avoid issue of losing some part of realtime audio input/video. If client wishes to temporarily disconnect (for example as result of receiving GoAway) they can do it without losing state by buffering messages sent since last `SessionResumptionTokenUpdate`. This field will enable them to limit buffering (avoid keeping all requests in RAM). Note: This should not be used for when resuming a session at some time later -- in those cases partial audio and video frames are likely not needed. - `liveSessionId` string, nullable - `goAway` LiveServerGoAway — Server will not be able to service client soon. - `timeLeft` string, nullable — The remaining time before the connection will be terminated as ABORTED. The minimal time returned here is specified differently together with the rate limits for a given model. - `voiceActivity` VoiceActivity — Voice activity signal. - `voiceActivityType` 'TYPE_UNSPECIFIED' | 'ACTIVITY_START' | 'ACTIVITY_END' — The type of the voice activity signal. - `audioOffset` string, nullable — The time voice activity detected in audio time, relative to the start of the audio stream. - `inputTranscription` Transcription — Audio transcription in Server Content. - `text` string, nullable — Optional. Transcription text. - `finished` boolean, nullable — Optional. The bool indicates the end of the transcription. - `languageCode` string, nullable — The BCP-47 language code of the transcription. - `speakerLabel` string, nullable — A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). - `words` WordInfo[], nullable — Detailed word-level transcriptions and timing details. - `word` string, nullable — Transcript of the word. - `startOffset` string, nullable — Start offset in time of the word relative to the start of the audio. - `endOffset` string, nullable — End offset in time of the word relative to the start of the audio. - `outputTranscription` Transcription — Audio transcription in Server Content. - `text` string, nullable — Optional. Transcription text. - `finished` boolean, nullable — Optional. The bool indicates the end of the transcription. - `languageCode` string, nullable — The BCP-47 language code of the transcription. - `speakerLabel` string, nullable — A label identifying the speaker of this audio segment (e.g. "spk_1", "spk_2"). - `words` WordInfo[], nullable — Detailed word-level transcriptions and timing details. - `word` string, nullable — Transcript of the word. - `startOffset` string, nullable — Start offset in time of the word relative to the start of the audio. - `endOffset` string, nullable — End offset in time of the word relative to the start of the audio. - `avgLogprobs` number, nullable - `logprobsResult` LogprobsResult — The log probabilities of the tokens generated by the model. This is useful for understanding the model's confidence in its predictions and for debugging. For example, you can use log probabilities to identify when the model is making a less confident prediction or to explore alternative responses that the model considered. A low log probability can also indicate that the model is "hallucinating" or generating factually incorrect information. - `chosenCandidates` LogprobsResultCandidate[], nullable — A list of the chosen candidate tokens at each decoding step. The length of this list is equal to the total number of decoding steps. Note that the chosen candidate might not be in `top_candidates`. - `logProbability` number, nullable — The log probability of this token. A higher value indicates that the model was more confident in this token. The log probability can be used to assess the relative likelihood of different tokens and to identify when the model is uncertain. - `token` string, nullable — The token's string representation. - `tokenId` integer, nullable — The token's numerical ID. While the `token` field provides the string representation of the token, the `token_id` is the numerical representation that the model uses internally. This can be useful for developers who want to build custom logic based on the model's vocabulary. - `topCandidates` LogprobsResultTopCandidates[], nullable — A list of the top candidate tokens at each decoding step. The length of this list is equal to the total number of decoding steps. - `candidates` LogprobsResultCandidate[], nullable — The list of candidate tokens, sorted by log probability in descending order. - `logProbability` number, nullable — The log probability of this token. A higher value indicates that the model was more confident in this token. The log probability can be used to assess the relative likelihood of different tokens and to identify when the model is uncertain. - `token` string, nullable — The token's string representation. - `tokenId` integer, nullable — The token's numerical ID. While the `token` field provides the string representation of the token, the `token_id` is the numerical representation that the model uses internally. This can be useful for developers who want to build custom logic based on the model's vocabulary. - `logProbabilitySum` number, nullable — Sum of log probabilities for all tokens. This field is not supported in Vertex AI. - `cacheMetadata` CacheMetadata — Metadata for context cache associated with LLM responses. This class stores cache identification, usage tracking, and lifecycle information for a particular cache instance. It can be in two states: 1. Active cache state: cache_name is set, all fields populated 2. Fingerprint-only state: cache_name is None, only fingerprint and contents_count are set for prefix matching Token counts (cached and total) are available in the LlmResponse.usage_metadata and should be accessed from there to avoid duplication. Attributes: cache_name: The full resource name of the cached content (e.g., 'projects/123/locations/us-central1/cachedContents/456'). None when no active cache exists (fingerprint-only state). expire_time: Unix timestamp when the cache expires. None when no active cache exists. fingerprint: Hash of cacheable contents (instruction + tools + contents). Always present for prefix matching. invocations_used: Number of invocations this cache has been used for. None when no active cache exists. contents_count: Number of contents. When active cache exists, this is the count of cached contents. When no active cache exists, this is the count of the cacheable content prefix used for fingerprinting. created_at: Unix timestamp when the cache was created. None when no active cache exists. - `cache_name` string, nullable — Full resource name of the cached content (None if no active cache) - `expire_time` number, nullable — Unix timestamp when cache expires (None if no active cache) - `fingerprint` string, required — Hash of cacheable contents used to detect changes - `invocations_used` integer, nullable — Number of invocations this cache has been used for (None if no active cache) - `contents_count` integer, required — Number of contents (cached contents when active cache exists, cacheable content prefix when no active cache) - `created_at` number, nullable — Unix timestamp when cache was created (None if no active cache) - `citationMetadata` CitationMetadata — Citation information when the model quotes another source. - `citations` Citation[], nullable — Contains citation information when the model directly quotes, at length, from another source. Can include traditional websites and code repositories. - `endIndex` integer, nullable — Output only. The end index of the citation in the content. - `license` string, nullable — Output only. The license of the source of the citation. - `publicationDate` GoogleTypeDate — Represents a whole or partial calendar date, such as a birthday. The time of day and time zone are either specified elsewhere or are insignificant. The date is relative to the Gregorian Calendar. This can represent one of the following: * A full date, with non-zero year, month, and day values. * A month and day, with a zero year (for example, an anniversary). * A year on its own, with a zero month and a zero day. * A year and month, with a zero day (for example, a credit card expiration date). Related types: * google.type.TimeOfDay * google.type.DateTime * google.protobuf.Timestamp. This data type is not supported in Gemini API. - `day` integer, nullable — Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant. - `month` integer, nullable — Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day. - `year` integer, nullable — Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year. - `startIndex` integer, nullable — Output only. The start index of the citation in the content. - `title` string, nullable — Output only. The title of the source of the citation. - `uri` string, nullable — Output only. The URI of the source of the citation. - `interactionId` string, nullable - `environmentId` string, nullable - `invocationId` string - `author` string - `actions` EventActionsOutput — Represents the actions attached to an event. - `skipSummarization` boolean, nullable - `stateDelta` object - `artifactDelta` object - `transferToAgent` string, nullable - `escalate` boolean, nullable - `requestedAuthConfigs` object - `requestedToolConfirmations` object - `compaction` EventCompaction — The compaction of the events. - `startTimestamp` number, required - `endTimestamp` number, required - `compactedContent` Content, required — Contains the multi-part content of a message. - `parts` Part[], nullable — List of parts that constitute a single message. Each part may have a different IANA MIME type. - `mediaResolution` PartMediaResolution — Media resolution for the input media. - … - `codeExecutionResult` CodeExecutionResult — Result of executing the ExecutableCode. Generated only when the `CodeExecution` tool is used. - … - `executableCode` ExecutableCode — Code generated by the model that is meant to be executed, and the result returned to the model. Generated when using the `CodeExecution` tool, in which the code will be automatically executed, and a corresponding CodeExecutionResult will also be generated. - … - `fileData` FileData — URI-based data. A FileData message contains a URI pointing to data of a specific media type. It is used to represent images, audio, and video stored in Google Cloud Storage. - … - `functionCall` FunctionCall — A predicted FunctionCall returned from the model that contains a string representing the FunctionDeclaration.name and a structured JSON object containing the parameters and their values. - … - `functionResponse` FunctionResponse — The result output from a FunctionCall that contains a string representing the FunctionDeclaration.name and a structured JSON object containing any output from the function is used as context to the model. This should contain the result of a `FunctionCall` made based on model prediction. - … - `inlineData` Blob — A content blob. A Blob contains data of a specific media type. It is used to represent images, audio, and video. - … - `text` string, nullable — Optional. The text content of the part. When sent from the VSCode Gemini Code Assist extension, references to @mentioned items will be converted to markdown boldface text. For example `@my-repo` will be converted to and sent as `**my-repo**` by the IDE agent. - `thought` boolean, nullable — Optional. Indicates whether the `part` represents the model's thought process or reasoning. - `thoughtSignature` string, binary, nullable — Optional. An opaque signature for the thought so it can be reused in subsequent requests. - `videoMetadata` VideoMetadata — Provides metadata for a video, including the start and end offsets for clipping and the frame rate. - … - `toolCall` ToolCall — A predicted server-side `ToolCall` returned from the model. This message contains information about a tool that the model wants to invoke. The client is NOT expected to execute this `ToolCall`. Instead, the client should pass this `ToolCall` back to the API in a subsequent turn within a `Content` message, along with the corresponding `ToolResponse`. - … - `toolResponse` ToolResponse — The output from a server-side `ToolCall` execution. This message contains the results of a tool invocation that was initiated by a `ToolCall` from the model. The client should pass this `ToolResponse` back to the API in a subsequent turn within a `Content` message, along with the corresponding `ToolCall`. - … - `partMetadata` object, nullable — Custom metadata associated with the Part. Agents using genai.Part as content representation may need to keep track of the additional information. For example it can be name of a file/source from which the Part originates or a way to multiplex multiple Part streams. This field is not supported in Vertex AI. - `audioTranscription` Transcription — Audio transcription in Server Content. - … - `role` string, nullable — Optional. The producer of the content. Must be either 'user' or 'model'. If not set, the service will default to 'user'. - `endOfAgent` boolean, nullable - `agentState` object, nullable - `rewindBeforeInvocationId` string, nullable - `route` union - boolean - integer - string - union[] - union - boolean - integer - string - `renderUiWidgets` UiWidget[], nullable - `id` string, required - `provider` string, required - `payload` object - `setModelResponse` unknown - `output` unknown - `nodeInfo` NodeInfo — Workflow node metadata attached to an Event. - `path` string - `outputFor` string[], nullable - `messageAsOutput` boolean, nullable - `longRunningToolIds` string[], nullable - `branch` string, nullable - `isolationScope` string, nullable - `id` string - `timestamp` number - `lastUpdateTime` number — Unix timestamp in seconds for the most recent session update. ## Other responses - `422` — Validation Error ## Changes - **2026-07-31** `05dc9d47fcf0` — 16 info - added the new optional request property `anyOf[subschema #1: CreateSessionRequest]/events/anyOf[subschema #1]/items/actions/compaction/anyOf[subschema #1: EventCompaction]/compactedContent/parts/anyOf[subschema #1]/items/audioTranscription` - added the new optional request property `anyOf[subschema #1: CreateSessionRequest]/events/anyOf[subschema #1]/items/content/anyOf[subschema #1: Content]/parts/anyOf[subschema #1]/items/audioTranscription` - added the new optional request property `anyOf[subschema #1: CreateSessionRequest]/events/anyOf[subschema #1]/items/environmentId` - added the new optional request property `anyOf[subschema #1: CreateSessionRequest]/events/anyOf[subschema #1]/items/inputTranscription/anyOf[subschema #1: Transcription]/speakerLabel` - …12 more - …earlier changes not shown [Full history](https://skmtc.dev/google/apis/adk-rest-api-reference/changes/apps/:app_name/users/:user_id/sessions/post.md) --- [API](https://skmtc.dev/google/apis/adk-rest-api-reference.md) · [All operations](https://skmtc.dev/google/apis/adk-rest-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/google/adk-rest-api-reference/revisions/05dc9d47fcf0/schema)