# List Folders
Retrieves a paginated list of folders created under your account.
**Note:**
* Scroll down to the **Response** section below and expand the status code(s) to view the detailed response schema.
* Refer to the **RESPONSE** section on the right and choose an example to see how the API response appears for each status code.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "heygen-api",
"version": "4.0.8"
},
"servers": [
{
"url": "https://api.heygen.com"
}
],
"components": {
"securitySchemes": {
"sec0": {
"type": "apiKey",
"name": "x-api-key",
"in": "header",
"x-default": ""
}
}
},
"security": [
{
"sec0": []
}
],
"paths": {
"/v1/folders": {
"get": {
"summary": "List Folders",
"description": "Retrieves a list of folders with optional filters.",
"operationId": "list-folders",
"parameters": [
{
"name": "limit",
"in": "query",
"description": "Maximum number of folders to return in a single response. Accepts values from 0 to 100. If more than 100 folders are available, use the pagination token to retrieve additional results.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "parent_id",
"in": "query",
"description": "Filter folders by their parent folder ID. ",
"schema": {
"type": "string"
}
},
{
"name": "name_filter",
"in": "query",
"description": "Search for folders by full or partial name.",
"schema": {
"type": "string"
}
},
{
"name": "is_trash",
"in": "query",
"description": "Whether to retrieve folders that are in the trash. Returns only the deleted folders if set to `true`. ",
"schema": {
"type": "boolean"
}
},
{
"name": "token",
"in": "query",
"description": "Pagination token used to retrieve the next set of results when the total number of records exceeds the specified/default limit. _This token is returned in the response and can be included in the next request to continue listing remaining assets. If the token value is `null`, it indicates that all available results have been retrieved._",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Folders retrived successfully - Expand to view the detailed response schema.",
"content": {
"application/json": {
"examples": {
"Result": {
"value": {
"error": null,
"data": {
"folders": [
{
"id": "26bg0d662440460783efe9be2a17b32e",
"name": "Video Project",
"parent_id": null,
"project_type": "asset",
"is_trash": false,
"created_ts": 1760939075,
"updated_ts": 1760939075,
"direct_children_count": 4,
"creator_username": "05abafd83b8541f0b8256a14c8a4ce92"
},
{
"id": "7612e0f262804d8580e5551b4e5cd18c",
"name": "Gmail Brand Kit",
"parent_id": null,
"project_type": "brand_kit",
"is_trash": false,
"created_ts": 1760719458,
"updated_ts": 1760719458,
"direct_children_count": 0,
"creator_username": "05abafd83b8541f0b8256a14c8a4ce92"
}
],
"token": "eyJzb3J0X2tleSI6ICJjcmVhhFRkX3RzIiwgInNvcnRfb3JkZXIiOiAiZGVzYyIsICJzdGFydF9pZCI6ICI3NjQ0ZTBjMjYyODA0ZDg1OKOiMzU1MWI0ZTVjZjE4YyIsICJsYXN0X2NyZWF0ZWRfdHMiOiAxNz5wNzE5WDU4LCAibGFzdF9mZXRjaGVkX25hbWUiOiAiR21haWwgQnJhbmQgS2l0In0=",
"total": 7
}
}
}
},
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Displays error message when the request fails; null if the request is successful."
},
"data": {
"type": "object",
"properties": {
"folders": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the folder. "
},
"name": {
"type": "string",
"description": "Name of the folder. "
},
"parent_id": {
"type": "string",
"description": "Unique identifier of the parent folder. `null` if the folder is at root level. "
},
"project_type": {
"type": "string",
"description": "Type of project associated with the folder. For example, `video_translate`, `instant_avatar`, `video`, `asset`, `brand_kit`, and `mixed`. "
},
"is_trash": {
"type": "boolean",
"description": "Whether the folder is in the trash. "
},
"created_ts": {
"type": "integer",
"description": "Unix timestamp when the folder was created. "
},
"updated_ts": {
"type": "integer",
"description": "Unix timestamp when the folder was updated. "
},
"direct_children_count": {
"type": "integer",
"description": "Number of subfolders directly contained within the folder. "
},
"creator_username": {
"type": "string",
"description": "Unique identifier of the user who created the folder. "
}
},
"type": "object"
},
"description": "An array of folder objects. "
},
"total": {
"type": "integer",
"description": "Total number of folders created in the account. "
},
"token": {
"type": "string",
"description": "Pagination token used to retrieve the next set of results when the total exceeds the specified/default response limit."
}
},
"description": "Contains detailed information about the folders. "
}
}
}
}
}
}
},
"deprecated": false
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": true,
"proxy-enabled": true
},
"x-readme-fauxas": true
}
```