curl --request POST 'https://api.voicecheap.ai/v1/actions/usage_logs_list' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"view":"translation","fromDate":"2026-10-01","toDate":"2026-10-16","page":1,"pageSize":25}'
const input = {
view: 'translation',
fromDate: '2026-10-01',
toDate: '2026-10-16',
page: 1,
pageSize: 25,
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/usage_logs_list', {
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/usage_logs_list",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"view": "translation", "fromDate": "2026-10-01", "toDate": "2026-10-16", "page": 1, "pageSize": 25},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"exportedAt": 1792152000000,
"scope": "user",
"plan": "pro",
"view": "translation",
"filters": {
"view": "translation",
"lipSyncUsage": "all",
"translationStatuses": [],
"billingState": "all",
"fromDate": "2026-10-01",
"toDate": "2026-10-16"
},
"pagination": {
"page": 1,
"pageSize": 25,
"totalItems": 1,
"totalPages": 1
},
"totals": {
"translationBaseMinutes": 2,
"lipSyncExtraMinutes": 0,
"lipSyncProExtraMinutes": 0,
"lipSyncPro2ExtraMinutes": 0,
"totalChargedMinutes": 2,
"refundedMinutes": 0,
"netUsedMinutes": 2
},
"rows": [
{
"projectId": "project_123",
"projectName": "Product launch",
"workId": "work_123",
"translatedVersionId": "version_123",
"sourceLanguage": "english",
"targetLanguage": "french",
"startedAt": 1792065600000,
"endedAt": 1792065720000,
"startedByUserId": "user_123",
"translationStatus": "completed",
"lipSyncUsage": "none",
"lipSyncStatus": "not_used",
"runNumber": 1,
"totalChargedMinutes": 2,
"refundedMinutes": 0,
"netUsedMinutes": 2,
"billingState": "charged"
}
]
}
}
Usage and activity
List media usage
Get paginated translation and lip-sync minute consumption, charge and refund history, with optional date, language, status, and project filters.
POST
/
v1
/
actions
/
usage_logs_list
curl --request POST 'https://api.voicecheap.ai/v1/actions/usage_logs_list' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"view":"translation","fromDate":"2026-10-01","toDate":"2026-10-16","page":1,"pageSize":25}'
const input = {
view: 'translation',
fromDate: '2026-10-01',
toDate: '2026-10-16',
page: 1,
pageSize: 25,
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/usage_logs_list', {
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/usage_logs_list",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"view": "translation", "fromDate": "2026-10-01", "toDate": "2026-10-16", "page": 1, "pageSize": 25},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"exportedAt": 1792152000000,
"scope": "user",
"plan": "pro",
"view": "translation",
"filters": {
"view": "translation",
"lipSyncUsage": "all",
"translationStatuses": [],
"billingState": "all",
"fromDate": "2026-10-01",
"toDate": "2026-10-16"
},
"pagination": {
"page": 1,
"pageSize": 25,
"totalItems": 1,
"totalPages": 1
},
"totals": {
"translationBaseMinutes": 2,
"lipSyncExtraMinutes": 0,
"lipSyncProExtraMinutes": 0,
"lipSyncPro2ExtraMinutes": 0,
"totalChargedMinutes": 2,
"refundedMinutes": 0,
"netUsedMinutes": 2
},
"rows": [
{
"projectId": "project_123",
"projectName": "Product launch",
"workId": "work_123",
"translatedVersionId": "version_123",
"sourceLanguage": "english",
"targetLanguage": "french",
"startedAt": 1792065600000,
"endedAt": 1792065720000,
"startedByUserId": "user_123",
"translationStatus": "completed",
"lipSyncUsage": "none",
"lipSyncStatus": "not_used",
"runNumber": 1,
"totalChargedMinutes": 2,
"refundedMinutes": 0,
"netUsedMinutes": 2,
"billingState": "charged"
}
]
}
}
Get paginated translation and lip-sync minute consumption, charge and refund history, with optional date, language, status, and project filters.
Required permissions:
POST https://api.voicecheap.ai/v1/actions/usage_logs_list
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.
usage:read.
An active paid subscription is required. Permissions do not change team roles, resource ownership, media credits, or plan limits.
Parameters
string
Text value.Allowed values: “translation”, “project”. Default: “translation”.
string
Text value.Minimum length: 1. Maximum length: 200. Pattern:
^[^/]+$.string
Text value.Minimum length: 1. Maximum length: 200.
string
Text value.Minimum length: 2. Maximum length: 64.
string
Text value.Allowed values: “all”, “none”, “standard”, “pro”, “pro_2”.
array
List of values. See the complete input schema for its item structure.Maximum items: 4.
string
Text value.Allowed values: “all”, “charged”, “refunded”, “refund_pending”.
string
Text value.Format: “date”. Pattern:
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$.string
Text value.Format: “date”. Pattern:
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$.integer
Integer value.Minimum: 1. Maximum: 100000. Default: 1.
integer
Integer value.Minimum: 1. Maximum: 100. Default: 25.
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": {
"view": {
"default": "translation",
"type": "string",
"enum": ["translation", "project"]
},
"translatedVersionId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^/]+$"
},
"project": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"targetLanguage": {
"type": "string",
"minLength": 2,
"maxLength": 64
},
"lipSyncUsage": {
"type": "string",
"enum": ["all", "none", "standard", "pro", "pro_2"]
},
"translationStatuses": {
"maxItems": 4,
"type": "array",
"items": {
"type": "string",
"enum": ["in_progress", "completed", "failed", "timed_out"]
}
},
"billingState": {
"type": "string",
"enum": ["all", "charged", "refunded", "refund_pending"]
},
"fromDate": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"toDate": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"page": {
"default": 1,
"type": "integer",
"minimum": 1,
"maximum": 100000
},
"pageSize": {
"default": 25,
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"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/usage_logs_list' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"view":"translation","fromDate":"2026-10-01","toDate":"2026-10-16","page":1,"pageSize":25}'
const input = {
view: 'translation',
fromDate: '2026-10-01',
toDate: '2026-10-16',
page: 1,
pageSize: 25,
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/usage_logs_list', {
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/usage_logs_list",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"view": "translation", "fromDate": "2026-10-01", "toDate": "2026-10-16", "page": 1, "pageSize": 25},
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 paginated translation or project usage rows, normalized filters, and minute totals across all matching rows.{
"data": {
"exportedAt": 1792152000000,
"scope": "user",
"plan": "pro",
"view": "translation",
"filters": {
"view": "translation",
"lipSyncUsage": "all",
"translationStatuses": [],
"billingState": "all",
"fromDate": "2026-10-01",
"toDate": "2026-10-16"
},
"pagination": {
"page": 1,
"pageSize": 25,
"totalItems": 1,
"totalPages": 1
},
"totals": {
"translationBaseMinutes": 2,
"lipSyncExtraMinutes": 0,
"lipSyncProExtraMinutes": 0,
"lipSyncPro2ExtraMinutes": 0,
"totalChargedMinutes": 2,
"refundedMinutes": 0,
"netUsedMinutes": 2
},
"rows": [
{
"projectId": "project_123",
"projectName": "Product launch",
"workId": "work_123",
"translatedVersionId": "version_123",
"sourceLanguage": "english",
"targetLanguage": "french",
"startedAt": 1792065600000,
"endedAt": 1792065720000,
"startedByUserId": "user_123",
"translationStatus": "completed",
"lipSyncUsage": "none",
"lipSyncStatus": "not_used",
"runNumber": 1,
"totalChargedMinutes": 2,
"refundedMinutes": 0,
"netUsedMinutes": 2,
"billingState": "charged"
}
]
}
}
Result fields
| Field | Description |
|---|---|
data.exportedAt | Time the result was produced, as a Unix timestamp in milliseconds. |
data.scope | user for a personal account or team for an owned or joined team. |
data.plan | Workspace owner’s plan. |
data.view | translation or project, matching the requested view. |
data.filters | Normalized applied filters; pagination is returned separately. |
data.pagination.page | Page returned after applying the available page range. |
data.pagination.pageSize | Number of rows per page. |
data.pagination.totalItems | Total number of matching rows before pagination. |
data.pagination.totalPages | Number of pages; at least one even for an empty result. |
data.totals.translationBaseMinutes | Base translation minutes charged across the matching rows. |
data.totals.lipSyncExtraMinutes | Additional Standard lip-sync minutes charged. |
data.totals.lipSyncProExtraMinutes | Additional Pro lip-sync minutes charged. |
data.totals.lipSyncPro2ExtraMinutes | Additional Pro 2 lip-sync minutes charged. |
data.totals.totalChargedMinutes | Total minutes charged before refunds. |
data.totals.refundedMinutes | Minutes refunded. |
data.totals.netUsedMinutes | Charged minutes minus refunded minutes. |
data.rows | Translation rows in translation view, or project aggregates in project view. |
data.rows[].projectId | Project identifier. |
data.rows[].projectName | Project display name. |
data.rows[].workId | Work identifier, present in translation view. |
data.rows[].translatedVersionId | Translated version identifier, present in translation view. |
data.rows[].sourceLanguage | Source language. |
data.rows[].targetLanguage | Target language in translation view. |
data.rows[].startedAt | Translation start timestamp in milliseconds, in translation view. |
data.rows[].endedAt | Optional translation/lip-sync end timestamp in milliseconds, in translation view. |
data.rows[].startedByUserId | Optional initiating account identifier, in translation view. |
data.rows[].translationStatus | in_progress, completed, failed, or timed_out in translation view. |
data.rows[].lipSyncUsage | none, standard, pro, or pro_2 in translation view. |
data.rows[].lipSyncStatus | not_used, in_progress, completed, failed, or timed_out in translation view. |
data.rows[].runNumber | Translation run number within this project and target language, in translation view. |
data.rows[].createdAt | Project creation timestamp in milliseconds, in project view. |
data.rows[].targetLanguages | Target languages represented by the project aggregate, in project view. |
data.rows[].runCount | Number of matching translation runs for the project, in project view. |
data.rows[].translationSummary | Project-view counts: inProgress, completed, failed, timedOut, and retryCount. |
data.rows[].lipSyncSummary | Project-view counts: inProgress, completed, failed, timedOut, retryCount, and notUsed. |
data.rows[].totalChargedMinutes | Row’s total charged minutes before refunds. |
data.rows[].refundedMinutes | Row’s refunded minutes. |
data.rows[].netUsedMinutes | Row’s charged minutes minus refunds. |
data.rows[].billingState | charged, refunded, or refund_pending. |
Operation notes
- view defaults to translation, page to 1, and pageSize to 25; pageSize cannot exceed 100.
- Date filters use YYYY-MM-DD and compare the translation start date in Europe/Paris. fromDate cannot be after toDate.
- project searches project names and IDs without regard to letter case. translatedVersionId matches version IDs by substring in translation view and is ignored in project view.
- Totals cover all matching translation rows, before pagination. The project view aggregates those rows by project.
- Public rows omit initiating users’ email addresses and raw processing error messages.
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 | 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 | 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": ["usage:read"]
}
}
Was this page helpful?