curl --request POST 'https://api.voicecheap.ai/v1/actions/folders_get' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"folderId":"624f6bb2-e06f-4353-8d6a-33d15f34c5c2","includeProjectMetrics":true}'
const input = {
folderId: '624f6bb2-e06f-4353-8d6a-33d15f34c5c2',
includeProjectMetrics: true,
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/folders_get', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/folders_get",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"folderId": "624f6bb2-e06f-4353-8d6a-33d15f34c5c2", "includeProjectMetrics": True},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"folderId": "624f6bb2-e06f-4353-8d6a-33d15f34c5c2",
"folderName": "Product videos",
"projectIds": [
"project_123"
],
"dateCreated": 1792065600000,
"translationInstructions": "Keep product names unchanged.",
"projectMetrics": {
"projectsCount": 1,
"totalDurationSeconds": 120,
"translatedProjectsCount": 1,
"translationsInProgressProjectsCount": 0,
"awaitingProofreadingProjectsCount": 0
}
}
}
Folders
Get a folder
Get a folder’s name, translation instructions, project IDs, and optional project metrics in your active workspace.
POST
/
v1
/
actions
/
folders_get
curl --request POST 'https://api.voicecheap.ai/v1/actions/folders_get' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"folderId":"624f6bb2-e06f-4353-8d6a-33d15f34c5c2","includeProjectMetrics":true}'
const input = {
folderId: '624f6bb2-e06f-4353-8d6a-33d15f34c5c2',
includeProjectMetrics: true,
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/folders_get', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/folders_get",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"folderId": "624f6bb2-e06f-4353-8d6a-33d15f34c5c2", "includeProjectMetrics": True},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"folderId": "624f6bb2-e06f-4353-8d6a-33d15f34c5c2",
"folderName": "Product videos",
"projectIds": [
"project_123"
],
"dateCreated": 1792065600000,
"translationInstructions": "Keep product names unchanged.",
"projectMetrics": {
"projectsCount": 1,
"totalDurationSeconds": 120,
"translatedProjectsCount": 1,
"translationsInProgressProjectsCount": 0,
"awaitingProofreadingProjectsCount": 0
}
}
}
Get a folder’s name, translation instructions, project IDs, and optional project metrics in your active workspace.
Required permissions:
POST https://api.voicecheap.ai/v1/actions/folders_get
Authentication and permissions
string
required
Send a VoiceCheap API key in this header. Authorization: Bearer with the same API key is also supported. OAuth access tokens are accepted only by
MCP, not by this REST endpoint.
folders:read.
An active paid subscription is required. Permissions do not change team roles, resource ownership, media credits, or plan limits.
Parameters
string
required
Text value.Minimum length: 1. Maximum length: 200. Pattern:
^[^/]+$.boolean
Boolean value.Default: false.
Complete input schema
Complete input schema
The JSON Schema below preserves the exact field names, nested types, defaults, bounds, and accepted values exposed by discovery. Additional cross-field rules are listed in the operation notes.
{
"type": "object",
"properties": {
"folderId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^/]+$"
},
"includeProjectMetrics": {
"default": false,
"type": "boolean"
}
},
"required": ["folderId"],
"additionalProperties": false
}
Request examples
Replace example resource identifiers and media keys with values returned for your account. Keep the request identifier stable when retrying the same mutation.curl --request POST 'https://api.voicecheap.ai/v1/actions/folders_get' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"folderId":"624f6bb2-e06f-4353-8d6a-33d15f34c5c2","includeProjectMetrics":true}'
const input = {
folderId: '624f6bb2-e06f-4353-8d6a-33d15f34c5c2',
includeProjectMetrics: true,
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/folders_get', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/folders_get",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"folderId": "624f6bb2-e06f-4353-8d6a-33d15f34c5c2", "includeProjectMetrics": True},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
Response
A successful first execution returns HTTP 200 with the operation result under data. A replay may return saved request state instead. The example shows one supported response, not every optional field. Returns folder details, with current project metrics when requested.{
"data": {
"folderId": "624f6bb2-e06f-4353-8d6a-33d15f34c5c2",
"folderName": "Product videos",
"projectIds": [
"project_123"
],
"dateCreated": 1792065600000,
"translationInstructions": "Keep product names unchanged.",
"projectMetrics": {
"projectsCount": 1,
"totalDurationSeconds": 120,
"translatedProjectsCount": 1,
"translationsInProgressProjectsCount": 0,
"awaitingProofreadingProjectsCount": 0
}
}
}
Result fields
| Field | Description |
|---|---|
data.folderId | Folder identifier. Use the returned value in subsequent folder actions. |
data.folderName | Current folder name. |
data.projectIds | Identifiers of accessible projects assigned to this folder. |
data.dateCreated | Folder creation time as a Unix timestamp in milliseconds. |
data.translationInstructions | Translation instructions saved on the folder; an empty string means none. |
data.projectMetrics | Present when metrics were requested. |
data.projectMetrics.projectsCount | Number of accessible projects included in projectIds. |
data.projectMetrics.totalDurationSeconds | Combined source duration in seconds. |
data.projectMetrics.translatedProjectsCount | Projects marked as translated in all their target languages. |
data.projectMetrics.translationsInProgressProjectsCount | Projects with translations in progress. |
data.projectMetrics.awaitingProofreadingProjectsCount | Projects awaiting proofreading. |
Operation notes
- includeProjectMetrics defaults to false. Metrics are omitted unless requested.
- For team guests, projectIds and requested metrics include only projects they created through the API in the active team. Saved results and replays apply the same project access checks.
Usage
Each successful invocation consumes one monthly API/MCP call. Media credits and the operation’s own generation allowances also apply.Errors
| HTTP status | Code | Meaning or recovery |
|---|---|---|
| 400 | BAD_REQUEST | The folder or required workspace account was not found. |
| 400 | CREDENTIAL_IN_QUERY | Credentials were supplied in an access_token or api_key query parameter. Send credentials in headers. |
| 400 | VALIDATION_ERROR | The JSON object contains an unsupported field, an invalid value, or a missing required argument. |
| 401 | API_KEY_EXPIRED | The API key has expired. |
| 401 | INVALID_API_KEY | Provide a valid, unexpired API key. |
| 401 | INVALID_CREDENTIAL | The Authorization header is malformed or conflicts with x-api-key. |
| 401 | MISSING_CREDENTIAL | No usable header credential was supplied, or it exceeded 4096 characters. |
| 401 | UNAUTHORIZED | The folder does not belong to the active workspace. |
| 401 | USER_NOT_FOUND | The credential’s account no longer exists. |
| 403 | AMBIGUOUS_TEAM_API_KEY | The credential’s user belongs to more than one team, so the billing context is ambiguous. |
| 403 | INSUFFICIENT_SCOPE | Grant every required permission or choose another credential. |
| 403 | INTEGRATION_PLAN_UNSUPPORTED | The account’s integration limits could not be verified. |
| 403 | SUBSCRIPTION_REQUIRED | Use an active paid subscription. |
| 403 | TEAM_MEMBERSHIP_INVALID | The account’s current team membership does not match this connection’s workspace. Refresh the membership and reconnect. |
| 403 | TEAM_OWNER_NOT_FOUND | The effective team owner account could not be found. |
| 404 | ACCOUNT_NOT_FOUND | The account or active workspace account could not be found. |
| 429 | INTEGRATION_MONTHLY_LIMIT_REACHED | Wait for the monthly reset or change plan. |
| 429 | INTEGRATION_RATE_LIMIT_REACHED | Wait for Retry-After when present and use backoff. |
| 500 | INTERNAL_ERROR | Check saved request state and resource history before deciding to retry a mutation. |
| 503 | SERVER_RESTARTING | The server is restarting. Retry shortly and keep the same request identifier for a mutation. |
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["folders:read"]
}
}
Was this page helpful?