---
title: "List files"
method: GET
path: "/v2/files"
tags: ["Files"]
---

# List files

`GET /v2/files`

Lists internal files, externally connected files and folders for a specific record. Use the `object` and `record_id` query parameters to specify the record. Optional query parameters may be provided to filter results by storage provider or parent folder.

This endpoint is in beta. We will aim to avoid breaking changes, but small updates may be made as we roll out to more users.

Required scopes: `object_configuration:read`, `record_permission:read`, `file:read`.

## Query parameters

- `object` string, required — The object slug or ID.
- `record_id` string, uuid, required — The record ID for the specific record whose files you want to list.
- `storage_provider` 'attio' | 'dropbox' | 'box' | 'google-drive' | 'microsoft-onedrive' — Filter results by storage provider.
- `parent_folder_id` string, uuid — Filter by parent folder ID. Each file entry has provided optioanl parent_folder_id that can be used to filter results by folder. When omitted, entries at all nesting levels are returned.
- `limit` integer — The maximum number of files to return. Must be between 1 and 200. Defaults to 50.
- `cursor` string — A pagination cursor used to fetch the next page of files. Responses with more files will include a cursor for you to use here. If not provided, the first page will be returned.

## Response `200`

Success

- object — Success
  - `data` union[], required
    - union
      - File
        - `id` object, required
          - `workspace_id` string, uuid, required — The ID of the workspace the file belongs to.
          - `file_id` string, uuid, required — The ID of the file entry.
        - `object_id` string, uuid, required — The ID of the object the record belongs to.
        - `object_slug` string, required — The slug of the object the record belongs to.
        - `record_id` string, uuid, required — The ID of the record the file is linked to.
        - `storage_provider` 'attio' | 'dropbox' | 'box' | 'google-drive' | 'microsoft-onedrive', required — The storage provider for this file entry.
        - `created_by_actor` object, required — The actor that created this file entry.
          - `id` string, nullable — An ID to identify the actor.
          - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors).
        - `created_at` string, required — Timestamp representing when the file entry was created.
        - `file_type` 'file', required — The type of file entry.
        - `name` string, required — The name of the file.
        - `content_type` string, nullable, required — The content type of the file.
        - `content_size` number, nullable, required — The size of the file in bytes.
        - `parent_folder_id` string, uuid, nullable, required — The ID of the parent folder, or null if this is a top-level file.
      - Folder
        - `id` object, required
          - `workspace_id` string, uuid, required — The ID of the workspace the file belongs to.
          - `file_id` string, uuid, required — The ID of the file entry.
        - `object_id` string, uuid, required — The ID of the object the record belongs to.
        - `object_slug` string, required — The slug of the object the record belongs to.
        - `record_id` string, uuid, required — The ID of the record the file is linked to.
        - `storage_provider` 'attio' | 'dropbox' | 'box' | 'google-drive' | 'microsoft-onedrive', required — The storage provider for this file entry.
        - `created_by_actor` object, required — The actor that created this file entry.
          - `id` string, nullable — An ID to identify the actor.
          - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors).
        - `created_at` string, required — Timestamp representing when the file entry was created.
        - `file_type` 'folder', required — The type of file entry.
        - `name` string, required — The name of the folder.
        - `parent_folder_id` string, uuid, nullable, required — The ID of the parent folder, or null if this is a top-level folder.
      - ConnectedFile
        - `id` object, required
          - `workspace_id` string, uuid, required — The ID of the workspace the file belongs to.
          - `file_id` string, uuid, required — The ID of the file entry.
        - `object_id` string, uuid, required — The ID of the object the record belongs to.
        - `object_slug` string, required — The slug of the object the record belongs to.
        - `record_id` string, uuid, required — The ID of the record the file is linked to.
        - `storage_provider` 'attio' | 'dropbox' | 'box' | 'google-drive' | 'microsoft-onedrive', required — The storage provider for this file entry.
        - `created_by_actor` object, required — The actor that created this file entry.
          - `id` string, nullable — An ID to identify the actor.
          - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors).
        - `created_at` string, required — Timestamp representing when the file entry was created.
        - `file_type` 'connected-file', required — The type of file entry.
        - `external_provider_file_id` string, required — The file ID in the external storage provider.
        - `microsoft_drive_id` string, nullable, required — Microsoft drive ID. This field is only populated for `microsoft-onedrive` entries.
      - ConnectedFolder
        - `id` object, required
          - `workspace_id` string, uuid, required — The ID of the workspace the file belongs to.
          - `file_id` string, uuid, required — The ID of the file entry.
        - `object_id` string, uuid, required — The ID of the object the record belongs to.
        - `object_slug` string, required — The slug of the object the record belongs to.
        - `record_id` string, uuid, required — The ID of the record the file is linked to.
        - `storage_provider` 'attio' | 'dropbox' | 'box' | 'google-drive' | 'microsoft-onedrive', required — The storage provider for this file entry.
        - `created_by_actor` object, required — The actor that created this file entry.
          - `id` string, nullable — An ID to identify the actor.
          - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors).
        - `created_at` string, required — Timestamp representing when the file entry was created.
        - `file_type` 'connected-folder', required — The type of file entry.
        - `external_provider_file_id` string, required — The file ID in the external storage provider.
        - `microsoft_drive_id` string, nullable, required — Microsoft drive ID. This field is only populated for `microsoft-onedrive` entries.
  - `pagination` object, required
    - `next_cursor` string, nullable, required

---

[API](https://skmtc.net/attio/apis/attio-api.md) · [All operations](https://skmtc.net/attio/apis/attio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/attio/attio-api/revisions/6ad6c02e6af9/schema)