Method: projects.locations.collections.engines.sessions.files.list

Lists metadata for all files in the current session.

HTTP request

GET https://discoveryengine.googleapis.com/v1alpha/{parent=projects/*/locations/*/collections/*/engines/*/sessions/*}/files

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
parent

string

Required. The resource name of the Session. Format: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session} name of the session resource to which the file belong.

Query parameters

Parameters
filter

string

Optional. The filter syntax consists of an expression language for constructing a predicate from one or more fields of the files being filtered. Filter expression is case-sensitive. Currently supported field names are: * uploadTime * lastAddTime * lastUseTime * fileName * mimeType

Some examples of filters would be: * "fileName = 'file_1'" * "fileName = 'file_1' AND mimeType = 'text/plain'" * "lastUseTime > '2025-06-14T12:00:00Z'"

For a full description of the filter format, please see https://google.aip.dev/160.
pageSize

integer

Optional. The maximum number of files to return. The service may return fewer than this value. If unspecified, at most 100 files will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. If user specifies a value less than or equal to 0 - the request will be rejected with an INVALID_ARGUMENT error.
pageToken

string

Optional. A page token received from a previous files.list call. Provide this to retrieve the subsequent page.

When paginating, all other parameters provided to files.list must match the call that provided the page token (except pageSize, which may differ).

Request body

The request body must be empty.

Response body

Response message for SessionService.ListFiles method.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "files": [
    {
      object (FileMetadata)
    }
  ],
  "nextPageToken": string
}
Fields
files[]

object (FileMetadata)

The FileMetadatas.
nextPageToken

string

A token to retrieve next page of results. Pass this value in the ListFilesRequest.page_token field in the subsequent call to files.list method to retrieve the next page of results.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the parent resource:

  • discoveryengine.sessions.listSessionFileMetadata

For more information, see the IAM documentation.

FileMetadata

Represents a file attached to a session (context file)

JSON representation 
{
  "fileId": string,
  "name": string,
  "mimeType": string,
  "byteSize": string,
  "originalUri": string,
  "originalSourceType": enum (FileSource),
  "uploadTime": string,
  "lastAddTime": string,
  "metadata": {
    string: string,
    ...
  },
  "downloadUri": string,
  "fileOriginType": enum (FileOriginType),
  "views": {
    string: {
      object (FileView)
    },
    ...
  }
}
Fields
fileId

string

Output only. The ID of the file.
name

string

Output only. The name of the file uploaded.
mimeType

string

The content type of the file, see https://www.iana.org/assignments/media-types/media-types.xhtml.
byteSize

string (int64 format)

Output only. The size of the context file in bytes.
originalUri

string

Optional. The original location of the file. It may be a local file path, or any other URI that allows accessing the file in an external system. There are two scenarios in which this url may be empty: 1. If the file was sent as inline data (e.g. pasted from the clipboard). 2. If the original location is not available.

Note that there's no guarantee that the URI will be pointing to a valid or actually existing file. For example, a file might have been uploaded to the session, and then deleted from the original source.
originalSourceType

enum (FileSource)

Optional. The type of the original source of the file.
uploadTime

string (Timestamp format)

Output only. The time the file was uploaded (If this is a file generated by an internal process and then made available to the session, this indicates the moment it happened).

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
lastAddTime

string (Timestamp format)

Output only. The time the file was added to the session. Note that if a file was added, then modified externally, then added again, the add time will be updated.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
metadata

map (key: string, value: string)

Optional. Represents metadata related to the file that can suit particular use cases. The prefix "google." is reserved for the key for use by Google, but other prefixes can be freely used.
downloadUri

string

Output only. The AssistantService.DownloadSessionFile URL to download the file. This URL will need the same credentials as AssistantService.ListSessionFileMetadata method and will provide the resource.
fileOriginType

enum (FileOriginType)

Optional. The origin of the file.
views

map (key: string, value: object (FileView))

Output only. Alternate views of this file object. Each file view is attached to a specific role. Possible example keys: - "thumbnail" - "mobile_thumbnail" - "clip" - "summary" - "translation"

FileOriginType

The origin of the file.

Enums
FILE_ORIGIN_TYPE_UNSPECIFIED Default value.
USER_PROVIDED The file was provided by the user.
AI_GENERATED The file was generated by an AI model.
INTERNALLY_GENERATED The file was generated from other files by an internal process.

FileView

Represents a specific alternate version or "view" of a file object, such as a summary, a thumbnail, a translated version, etc.

JSON representation 
{
  "viewId": string,
  "uri": string,
  "mimeType": string,
  "byteSize": string,
  "createTime": string,

  // Union field characteristics can be only one of the following:
  "imageCharacteristics": {
    object (ImageCharacteristics)
  },
  "videoCharacteristics": {
    object (VideoCharacteristics)
  },
  "fileCharacteristics": {
    object (FileCharacteristics)
  }
  // End of list of possible types for union field characteristics.
}
Fields
viewId

string

Output only. Globally Unique id for this specific view.
uri

string

Output only. The URI to access this media view.
mimeType

string

Output only. MIME type (e.g., "image/jpeg", "image/png", "text/plain", "video/mp4")
byteSize

string (int64 format)

Output only. The size of the view in bytes.
createTime

string (Timestamp format)

Output only. The time the view was created.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
Union field characteristics. Characteristics of the media view, allowing for flexible extensions. Metadata is always internally generated by the process creating the view. characteristics can be only one of the following:
imageCharacteristics

object (ImageCharacteristics)

Output only. Characteristics of an image media view.
videoCharacteristics

object (VideoCharacteristics)

Output only. Characteristics of a video media view.
fileCharacteristics

object (FileCharacteristics)

Output only. Characteristics of other file types.

ImageCharacteristics

Standard characteristics of an image media view.

JSON representation 
{
  "width": integer,
  "height": integer,
  "colorSpace": enum (ColorSpace),
  "bitDepth": integer
}
Fields
width

integer

Output only. Image width in pixels.
height

integer

Output only. Image height in pixels.
colorSpace

enum (ColorSpace)

Output only. color space of the image (e.g., "RGB", "CMYK", "Grayscale").
bitDepth

integer

Output only. Bit depth of the image (e.g., 8-bit, 16-bit).

ColorSpace

Possible color spaces of an image (e.g., "RGB", "CMYK", "Grayscale").

Enums
COLOR_SPACE_UNSPECIFIED Default value. Unknown color space.
RGB Red, green, blue colorspace.
CMYK Cyan, magenta, yellow, and black colorspace.
GRAYSCALE Grayscale colorspace.
YUV YUV colorspace.
OTHER_COLOR_SPACE Other colorspace.

VideoCharacteristics

Standard characteristics of a video media view.

JSON representation 
{
  "width": integer,
  "height": integer,
  "duration": string,
  "frameRate": number,
  "audioCodecs": [
    string
  ],
  "videoCodecs": [
    string
  ],
  "videoBitrateKbps": integer,
  "audioBitrateKbps": integer
}
Fields
width

integer

Output only. Video width in pixels.
height

integer

Output only. Video height in pixels.
duration

string (Duration format)

Output only. Video duration.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
frameRate

number

Output only. Frame rate (frames per second).
audioCodecs[]

string

Output only. Audio codecs used in the video.
videoCodecs[]

string

Output only. Video codecs used in the video.
videoBitrateKbps

integer

Output only. Bitrate of the video in kbps.
audioBitrateKbps

integer

Output only. Bitrate of the audio in kbps.

FileCharacteristics

Caracteristics of other file types.

JSON representation 
{
  "characteristics": {
    string: string,
    ...
  }
}
Fields
characteristics

map (key: string, value: string)

Output only. Generic map of characteristics.