> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Listar el uso multimedia
> Obtén el consumo de minutos de traducción y sincronización labial y el historial de cargos y reembolsos, con paginación y filtros opcionales de fecha, idioma, estado y proyecto.
Obtén el consumo de minutos de traducción y sincronización labial y el historial de cargos y reembolsos, con paginación y filtros opcionales de fecha, idioma, estado y proyecto.
```http theme={null}
POST https://api.voicecheap.ai/v1/actions/usage_logs_list
```
## Autenticación y permisos
Envía una clave de API de VoiceCheap en esta cabecera. También se admite Authorization: Bearer con la misma clave de API. Los tokens de acceso OAuth
solo se aceptan en MCP, no en este endpoint REST.
Permisos necesarios: `usage:read`.
Se requiere una suscripción de pago activa. Los permisos no cambian los roles del equipo, la propiedad de los recursos, los créditos multimedia ni los límites del plan.
## Parámetros
Valor de texto.
Valores permitidos: "translation", "project". Valor predeterminado: "translation".
Valor de texto.
Longitud mínima: 1. Longitud máxima: 200. Patrón: `^[^/]+$`.
Valor de texto.
Longitud mínima: 1. Longitud máxima: 200.
Valor de texto.
Longitud mínima: 2. Longitud máxima: 64.
Valor de texto.
Valores permitidos: "all", "none", "standard", "pro", "pro\_2".
Lista de valores. Consulta la estructura de sus elementos en el esquema completo de entrada.
Número máximo de elementos: 4.
Valor de texto.
Valores permitidos: "all", "charged", "refunded", "refund\_pending".
Valor de texto.
Formato: "date". Patrón: `^(?:(?:\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])))$`.
Valor de texto.
Formato: "date". Patrón: `^(?:(?:\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])))$`.
Valor entero.
Mínimo: 1. Máximo: 100000. Valor predeterminado: 1.
Valor entero.
Mínimo: 1. Máximo: 100. Valor predeterminado: 25.
El JSON Schema siguiente conserva los nombres exactos de los campos, los tipos anidados, los valores predeterminados, los límites y los valores aceptados que expone el descubrimiento. Las reglas adicionales entre campos se indican en las notas de la operación.
```json theme={null}
{
"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
}
```
## Ejemplos de solicitud
Sustituye los identificadores de recursos y las claves multimedia de los ejemplos por valores devueltos para tu cuenta. Mantén el identificador de solicitud al reintentar la misma modificación.
```bash cURL theme={null}
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}'
```
```javascript JavaScript theme={null}
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);
```
```python Python theme={null}
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)
```
## Respuesta
Una primera ejecución correcta devuelve HTTP 200 con el resultado de la operación en data. Una repetición puede devolver el estado de la solicitud guardada en su lugar. El ejemplo muestra una respuesta admitida, no todos los campos opcionales.
Devuelve filas paginadas de uso de traducciones o proyectos, filtros normalizados y totales de minutos de todas las filas coincidentes.
```json HTTP 200 theme={null}
{
"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"
}
]
}
}
```
## Campos del resultado
| Campo | Descripción |
| - | - |
| `data.exportedAt` | Momento en que se produjo el resultado, como marca de tiempo Unix en milisegundos. |
| `data.scope` | user para una cuenta personal o team para un equipo propio o al que se haya unido la cuenta. |
| `data.plan` | Plan del propietario del espacio de trabajo. |
| `data.view` | translation o project, según la vista solicitada. |
| `data.filters` | Filtros aplicados normalizados; la paginación se devuelve por separado. |
| `data.pagination.page` | Página devuelta tras aplicar el intervalo de páginas disponible. |
| `data.pagination.pageSize` | Número de filas por página. |
| `data.pagination.totalItems` | Número total de filas coincidentes antes de la paginación. |
| `data.pagination.totalPages` | Número de páginas; al menos una incluso si el resultado está vacío. |
| `data.totals.translationBaseMinutes` | Minutos de traducción base cobrados en las filas coincidentes. |
| `data.totals.lipSyncExtraMinutes` | Minutos adicionales de sincronización labial Standard cobrados. |
| `data.totals.lipSyncProExtraMinutes` | Minutos adicionales de sincronización labial Pro cobrados. |
| `data.totals.lipSyncPro2ExtraMinutes` | Minutos adicionales de sincronización labial Pro 2 cobrados. |
| `data.totals.totalChargedMinutes` | Total de minutos cobrados antes de los reembolsos. |
| `data.totals.refundedMinutes` | Minutos reembolsados. |
| `data.totals.netUsedMinutes` | Minutos cobrados menos minutos reembolsados. |
| `data.rows` | Filas de traducción en la vista de traducción, o agregados de proyectos en la vista de proyecto. |
| `data.rows[].projectId` | Identificador del proyecto. |
| `data.rows[].projectName` | Nombre visible del proyecto. |
| `data.rows[].workId` | Identificador del trabajo, presente en la vista de traducción. |
| `data.rows[].translatedVersionId` | Identificador de la versión traducida, presente en la vista de traducción. |
| `data.rows[].sourceLanguage` | Idioma de origen. |
| `data.rows[].targetLanguage` | Idioma de destino en la vista de traducción. |
| `data.rows[].startedAt` | Marca de tiempo de inicio de la traducción en milisegundos, en la vista de traducción. |
| `data.rows[].endedAt` | Marca de tiempo opcional de finalización de traducción o sincronización labial en milisegundos, en la vista de traducción. |
| `data.rows[].startedByUserId` | Identificador opcional de la cuenta que inició la operación, en la vista de traducción. |
| `data.rows[].translationStatus` | in\_progress, completed, failed o timed\_out en la vista de traducción. |
| `data.rows[].lipSyncUsage` | none, standard, pro o pro\_2 en la vista de traducción. |
| `data.rows[].lipSyncStatus` | not\_used, in\_progress, completed, failed o timed\_out en la vista de traducción. |
| `data.rows[].runNumber` | Número de ejecución de traducción dentro de este proyecto e idioma de destino, en la vista de traducción. |
| `data.rows[].createdAt` | Marca de tiempo de creación del proyecto en milisegundos, en la vista de proyecto. |
| `data.rows[].targetLanguages` | Idiomas de destino representados por el agregado del proyecto, en la vista de proyecto. |
| `data.rows[].runCount` | Número de ejecuciones de traducción coincidentes del proyecto, en la vista de proyecto. |
| `data.rows[].translationSummary` | Recuentos de la vista de proyecto: inProgress, completed, failed, timedOut y retryCount. |
| `data.rows[].lipSyncSummary` | Recuentos de la vista de proyecto: inProgress, completed, failed, timedOut, retryCount y notUsed. |
| `data.rows[].totalChargedMinutes` | Total de minutos cobrados de la fila antes de los reembolsos. |
| `data.rows[].refundedMinutes` | Minutos reembolsados de la fila. |
| `data.rows[].netUsedMinutes` | Minutos cobrados de la fila menos reembolsos. |
| `data.rows[].billingState` | charged, refunded o refund\_pending. |
## Notas de la operación
* view tiene como valor predeterminado translation, page 1 y pageSize 25; pageSize no puede superar 100.
* Los filtros de fecha usan YYYY-MM-DD y comparan la fecha de inicio de la traducción en Europe/Paris. fromDate no puede ser posterior a toDate.
* project busca nombres e ID de proyectos sin distinguir mayúsculas de minúsculas. translatedVersionId busca coincidencias por subcadena en los ID de versión en la vista de traducciones y se ignora en la vista de proyectos.
* Los totales incluyen todas las filas de traducción coincidentes antes de la paginación. La vista de proyectos agrupa esas filas por proyecto.
* Las filas públicas omiten las direcciones de correo electrónico de los usuarios que iniciaron la acción y los mensajes de error de procesamiento sin procesar.
## Uso
Cada invocación correcta consume una llamada mensual de API/MCP. También se aplican los créditos multimedia y las cuotas de generación propias de la operación.
## Errores
| Estado HTTP | Código | Significado o solución |
| - | - | - |
| 400 | `CREDENTIAL_IN_QUERY` | Se han proporcionado credenciales en un parámetro de consulta access\_token o api\_key. Envía las credenciales en las cabeceras. |
| 400 | `VALIDATION_ERROR` | El objeto JSON contiene un campo no compatible, un valor no válido o un argumento obligatorio ausente. |
| 401 | `API_KEY_EXPIRED` | La clave API ha caducado. |
| 401 | `INVALID_API_KEY` | Proporciona una clave de API válida que no haya caducado. |
| 401 | `INVALID_CREDENTIAL` | La cabecera Authorization tiene un formato incorrecto o entra en conflicto con x-api-key. |
| 401 | `MISSING_CREDENTIAL` | No se proporcionó ninguna credencial de cabecera utilizable o superaba 4096 caracteres. |
| 401 | `USER_NOT_FOUND` | La cuenta de la credencial ya no existe. |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | El usuario de la credencial pertenece a más de un equipo, por lo que el contexto de facturación es ambiguo. |
| 403 | `INSUFFICIENT_SCOPE` | Concede todos los permisos necesarios o elige otra credencial. |
| 403 | `INTEGRATION_PLAN_UNSUPPORTED` | No se han podido verificar los límites de integración de la cuenta. |
| 403 | `SUBSCRIPTION_REQUIRED` | Usa una suscripción de pago activa. |
| 403 | `TEAM_MEMBERSHIP_INVALID` | La membresía actual de la cuenta en el equipo no coincide con el espacio de trabajo de esta conexión. Actualiza la membresía y vuelve a conectar. |
| 403 | `TEAM_OWNER_NOT_FOUND` | No se pudo encontrar la cuenta del propietario efectivo del equipo. |
| 404 | `ACCOUNT_NOT_FOUND` | No se pudo encontrar la cuenta o la cuenta del espacio de trabajo activo. |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Espera al restablecimiento mensual o cambia de plan. |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Espera el tiempo indicado en Retry-After cuando esté presente y aplica esperas progresivas. |
| 500 | `INTERNAL_ERROR` | Comprueba el estado de la solicitud guardada y el historial del recurso antes de decidir si reintentas una modificación. |
| 503 | `SERVER_RESTARTING` | El servidor se está reiniciando. Reinténtalo en breve y conserva el mismo identificador de solicitud para una modificación. |
```json theme={null}
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["usage:read"]
}
}
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.