> ## AI Agent Context
> - Full documentation index: https://aistudio.google.com/llms.txt
> - Gemini Docs MCP server (consistent live info): https://gemini-api-docs-mcp.dev
> - Coding agent skills & setup guide: https://aistudio.google.com/docs/coding-agents.md

# Listing files

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/files`

Lists the metadata for [`File`](/api-reference/files/list-files#Resource:File)s owned by the requesting project.

{% two-column-layout %}
  {% left-column %}
## Parameters  {% class="hide-from-toc" id="parameters" %}

  {% section class="api-ref-property-list" %}
  **pageSize**: `integer`

  Optional. Maximum number of [`File`](/api-reference/files/list-files#Resource:File)s to return per page. If unspecified, defaults to 10. Maximum `page_size` is 100.

  {% hr /%}

  **pageToken**: `string`

  Optional. A page token from a previous `ListFiles` call.

  {% /section %}

  {% /left-column %}

  {% right-column class="sticky" %}
  **Example request** {% class="example-heading" %}

  {% tabs %}
  {% tab label="REST" %}
  ```sh
  echo "My files: "
  
  curl "https://generativelanguage.googleapis.com/v1beta/files?key=$GEMINI_API_KEY"
  ```

  {% /tab %}

  {% tab label="Python" %}
  ```python
  from google import genai
  
  client = genai.Client()
  print("My files:")
  for f in client.files.list():
    print("  ", f.name)
  ```

  {% /tab %}

  {% tab label="JavaScript" %}
  ```javascript
  // Make sure to include the following import:
  // import {GoogleGenAI} from '@google/genai';
  const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});
  console.log('My files:');
  // Using the pager style to list files
  const pager = await ai.files.list({config: {pageSize: 10}});
  let page = pager.page;
  const names = [];
  while (true) {
    for (const f of page) {
      console.log('  ', f.name);
      names.push(f.name);
    }
    if (!pager.hasNextPage()) break;
    page = await pager.nextPage();
  }
  ```

  {% /tab %}

  {% tab label="Go" %}
  ```go
  ctx := context.Background()
  client, err := genai.NewClient(ctx, &genai.ClientConfig{
      APIKey:  os.Getenv("GEMINI_API_KEY"),
      Backend: genai.BackendGeminiAPI,
  })
  if err != nil {
      log.Fatal(err)
  }
  fmt.Println("My files:")
  page, err := client.Files.List(ctx, nil)
  if err != nil {
      log.Fatal(err)
  }
  for _, f := range page.Items {
      fmt.Println("  ", f.Name)
  }
  ```

  {% /tab %}

  {% /tabs %}

  {% /right-column %}

{% /two-column-layout %}

## Response  {% class="hide-from-toc" id="response" %}

{% section class="api-ref-property-list" %}
  **files**: [`File`](/api-reference/files/list-files#Resource:File) `array`

  The list of [`File`](/api-reference/files/list-files#Resource:File)s.

  {% hr /%}

  **nextPageToken**: `string`

  A token that can be sent as a `page_token` into a subsequent `ListFiles` call.

{% /section %}

## Resources  {% class="hide-from-toc" id="resources" %}

### File  {% class="hide-from-toc" id="Resource:File" %}

A file uploaded to the API.

**Properties:**

{% section class="api-ref-property-list" %}
  {% details %}
  {% summary %}
  **metadata**: `Union type`

  Metadata for the File.

  {% /summary %}

  Union field `metadata` can be only one of the following:

  {% details %}
  {% summary %}
  **videoMetadata**: `VideoFileMetadata`

  Output only. Metadata for a video.

  {% /summary %}

  **videoDuration**: `string`

  Duration of the video.

  {% /details %}

  {% /details %}

  {% hr /%}

  **name**: `string`

  Immutable. Identifier. The [`File`](/api-reference/files/list-files#Resource:File) resource name. The ID (name excluding the "files/" prefix) can contain up to 40 characters that are lowercase alphanumeric or dashes (-). The ID cannot start or end with a dash. If the name is empty on create, a unique name will be generated. Example: `files/123-456`

  {% hr /%}

  **displayName**: `string`

  Optional. The human-readable display name for the [`File`](/api-reference/files/list-files#Resource:File). The display name must be no more than 512 characters in length, including spaces. Example: "Welcome Image"

  {% hr /%}

  **mimeType**: `string`

  Output only. MIME type of the file.

  {% hr /%}

  **sizeBytes**: `string`

  Output only. Size of the file in bytes.

  {% hr /%}

  **createTime**: `string`

  Output only. The timestamp of when the [`File`](/api-reference/files/list-files#Resource:File) was created.

  {% hr /%}

  **updateTime**: `string`

  Output only. The timestamp of when the [`File`](/api-reference/files/list-files#Resource:File) was last updated.

  {% hr /%}

  **expirationTime**: `string`

  Output only. The timestamp of when the [`File`](/api-reference/files/list-files#Resource:File) will be deleted. Only set if the [`File`](/api-reference/files/list-files#Resource:File) is scheduled to expire.

  {% hr /%}

  **sha256Hash**: `string`

  Output only. SHA-256 hash of the uploaded bytes.

  {% hr /%}

  **uri**: `string`

  Output only. The uri of the [`File`](/api-reference/files/list-files#Resource:File).

  {% hr /%}

  **downloadUri**: `string`

  Output only. The download uri of the [`File`](/api-reference/files/list-files#Resource:File).

  {% hr /%}

  {% details %}
  {% summary %}
  **state**: `string enum`

  Output only. Processing state of the File.

  {% /summary %}

  Possible values:

  - `STATE_UNSPECIFIED`: The default value. This value is used if the state is omitted.
  - `PROCESSING`: File is being processed and cannot be used for inference yet.
  - `ACTIVE`: File is processed and available for inference.
  - `FAILED`: File failed processing.

  {% /details %}

  {% hr /%}

  {% details %}
  {% summary %}
  **source**: `string enum`

  Source of the File.

  {% /summary %}

  Possible values:

  - `SOURCE_UNSPECIFIED`: Used if source is not specified.
  - `UPLOADED`: Indicates the file is uploaded by the user.
  - `GENERATED`: Indicates the file is generated by Google.
  - `REGISTERED`: Indicates the file is a registered, i.e. a Google Cloud Storage file.

  {% /details %}

  {% hr /%}

  **error**: [`Status`](/api-reference/files/list-files#Resource:Status)

  Output only. Error status if File processing failed.

{% /section %}

## Data Models  {% class="hide-from-toc" id="data-models" %}

### Status  {% class="hide-from-toc" id="Resource:Status" %}

The [`Status`](/api-reference/files/list-files#Resource: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`](/api-reference/files/list-files#Resource: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).

**Properties:**

{% section class="api-ref-property-list" %}
  **code**: `integer`

  The status code, which should be an enum value of google.rpc.Code.

  {% hr /%}

  **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.

  {% hr /%}

  **details**: `object array`

  A list of messages that carry the error details. There is a common set of message types for APIs to use.

{% /section %}

