--- updatedAt: 2026-04-20T20:26:21.000Z agentTools: projectIndex: https://docs.wistia.com/llms.txt --- # List Subfolders Lists subfolders in a specific folder. ## Requires api token with one of the following permissions ``` Read all folder and media data ``` Tokens with the "Act with a team member's permissions" permission (`all:delegate_to_contact_permissions` scope) can also be used. Requests made with such a token are authorized using the permissions of the contact assigned to the token. An [expiring access token](https://docs.wistia.com/reference/post_expiring-token) created with the `all:delegate_to_contact_permissions` scope and an authorization naming this folder (any permission) can also be used; it lists the folder's subfolders. # OpenAPI definition ````json { "openapi": "3.1.1", "info": { "title": "Data API", "description": "Wistia Data API", "version": "2026.09.0" }, "servers": [ { "url": "https://api.wistia.com/modern" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Subfolders" } ], "paths": { "/folders/{folderId}/subfolders": { "get": { "summary": "List Subfolders", "x-speakeasy-group": "subfolders", "x-speakeasy-name-override": "list", "description": "Lists subfolders in a specific folder.\n\n## Requires api token with one of the following permissions\n```\nRead all folder and media data\n```\n\nTokens with the \"Act with a team member's permissions\" permission\n(`all:delegate_to_contact_permissions` scope) can also be used. Requests\nmade with such a token are authorized using the permissions of the\ncontact assigned to the token.\n\nAn [expiring access token](https://docs.wistia.com/reference/post_expiring-token)\ncreated with the `all:delegate_to_contact_permissions` scope and an\nauthorization naming this folder (any permission) can also be used; it\nlists the folder's subfolders.\n", "parameters": [ { "name": "folderId", "in": "path", "description": "The hashed ID of the folder", "required": true, "schema": { "type": "string", "examples": [ "abc123def4" ] } }, { "name": "page", "in": "query", "description": "The page number to retrieve. This cannot be combined with `cursor`,\npagination.\n", "required": false, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "The number of medias per page. Use this for both offset pagination and cursor pagination.", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "description": "If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the\nfirst set of records are fetched up to the `per_page`. Cursor\npagination will also be turned on if `cursor[before]` or `cursor[after]`\nare set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering.\nThe cursor value of the last record can be used to fetch records after the current result set and\nthe cursor of the first record can be used to fetch records before the result set.\n\nNOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the\nlast fetch. For example, you cannot fetch using `sort_by` id and then pass that\ncursor value to a `sort_by` name.\n", "required": false, "schema": { "unevaluatedProperties": false, "type": "object", "properties": { "enabled": { "description": "If `cursor[enabled]` is set to 1, the first result set will be fetched with cursor pagination enabled. This\nvalues is ignored if `cursor[before]` or `cursor[after]` are set.\n", "type": "integer", "enum": [ 0, 1 ] }, "before": { "description": "If `cursor[before]` is set then cursor pagination is enabled and all records\nbefore the cursor up to the `per_page` are returned. This feature is useful for\nfetching \"new records\", for example, in a \"pull to refersh\" feature when showing records in a descending\norder.\n", "type": "string" }, "after": { "description": "If `cursor[after]` is set then cursor pagination is enabled and all records\nafter the cursor up to the `per_page` are returned.\n", "type": "string" } } }, "style": "deepObject" }, { "name": "sort_by", "in": "query", "description": "Field to sort by. When using cursor pagination (see cursor param),\nonly `id` is supported.\n", "required": false, "schema": { "type": "string", "default": "position", "enum": [ "name", "created", "updated", "position", "id" ] } }, { "name": "sort_direction", "in": "query", "description": "Sort direction (0 = desc, 1 = asc; default is 1)", "required": false, "schema": { "type": "integer", "default": 1, "enum": [ 0, 1 ] } }, { "name": "hashed_ids[]", "in": "query", "description": "Filter subfolders by their hashed IDs", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "explode": true, "style": "form" }, { "name": "X-Wistia-API-Version", "in": "header", "required": true, "schema": { "type": "string", "default": "2026-09" } } ], "responses": { "200": { "description": "A list of subfolders", "content": { "application/json": { "schema": { "type": "array", "items": { "unevaluatedProperties": false, "allOf": [ { "type": "object", "description": "A subfolder within a folder that contains media.", "properties": { "hashed_id": { "description": "A unique alphanumeric identifier for this subfolder.", "type": [ "string", "null" ], "examples": [ "abc123def4" ] }, "name": { "description": "The display name of the subfolder.", "type": [ "string", "null" ], "examples": [ "Marketing Videos" ] }, "description": { "description": "A description for the subfolder.", "type": [ "string", "null" ], "examples": [ "Collection of all marketing and promotional videos" ] }, "position": { "description": "The position of this subfolder within its folder, used for ordering.", "type": [ "integer", "null" ], "examples": [ 1 ] }, "created": { "description": "The date when the subfolder was created.", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2024-01-15T10:30:00+00:00" ] }, "updated": { "description": "The date when the subfolder was last modified.", "type": [ "string", "null" ], "format": "date-time", "examples": [ "2024-01-20T14:45:00+00:00" ] }, "cursor": { "description": "A cursor for stable pagination based on current `sort_by` order. You can pass this to `cursor[before]` or `cursor[after]` as a parameter to fetch the records before or after this record in the same sort order. This is only populated if records were fetched with `cursor[enabled]`, or `cursor[before]` or `cursor[after]`.", "type": [ "string", "null" ] } }, "required": [ "hashed_id", "position", "created", "updated" ] } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "unevaluatedProperties": false, "type": "object", "properties": { "error": { "description": "Error message detailing the reason for the bad request.", "type": "string", "examples": [ "Bad request" ] }, "errors": { "description": "Array of error messages detailing the reasons for the bad request.", "type": "array", "items": { "type": "string" } } } } } } }, "401": { "description": "Unauthorized, invalid or missing token", "content": { "application/json": { "schema": { "unevaluatedProperties": false, "type": "object", "properties": { "code": { "description": "A machine-readable identifier for the specific authorization failure.", "type": "string", "enum": [ "unauthorized_credentials", "account_inactive", "unauthorized_scope", "unauthorized_params" ] }, "error": { "type": "string", "examples": [ "Invalid credentials." ] } } } } } }, "404": { "description": "Folder not found", "content": { "application/json": { "schema": { "unevaluatedProperties": false, "type": "object", "properties": { "error": { "type": "string", "examples": [ "Folder with ID abc123def4 not found." ] } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "unevaluatedProperties": false, "type": "object", "properties": { "error": { "type": "string", "examples": [ "Internal server error" ] } } } } } } }, "tags": [ "Subfolders" ], "x-readme": { "code-samples": [ { "name": "Typescript (SDK)", "language": "javascript", "code": "import { Wistia } from \"@wistia/wistia-api-client\";\n\nconst wistia = new Wistia({\n bearerAuth: process.env[\"WISTIA_BEARER_AUTH\"] ?? \"\",\n});\n\nasync function run() {\n const result = await wistia.subfolders.list({\n folderId: \"abc123def4\",\n });\n\n console.log(result);\n}\n\nrun();" } ] } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } } }, "x-readme": { "samples-languages": [ "javascript", "shell", "node", "python", "ruby" ] } } ````