> ## 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 uso de mídia

> Consulte o consumo de minutos de tradução e sincronização labial e o histórico de cobranças e reembolsos, com paginação e filtros opcionais de data, idioma, status e projeto.

Consulte o consumo de minutos de tradução e sincronização labial e o histórico de cobranças e reembolsos, com paginação e filtros opcionais de data, idioma, status e projeto.

```http theme={null}
POST https://api.voicecheap.ai/v1/actions/usage_logs_list
```

## Autenticação e permissões

**x-api-key** `string` *required*

Envie uma chave de API VoiceCheap neste cabeçalho. Authorization: Bearer com a mesma chave de API também é aceito. Tokens de acesso OAuth são
aceitos apenas pelo MCP, não por este endpoint REST.

Permissões necessárias: `usage:read`.

É necessária uma assinatura paga ativa. As permissões não alteram funções na equipe, propriedade dos recursos, créditos de mídia ou limites do plano.

## Parâmetros

**view** `string`

Valor de texto.

Valores aceitos: "translation", "project". Valor padrão: "translation".

**translatedVersionId** `string`

Valor de texto.

Comprimento mínimo: 1. Comprimento máximo: 200. Padrão: `^[^/]+$`.

**project** `string`

Valor de texto.

Comprimento mínimo: 1. Comprimento máximo: 200.

**targetLanguage** `string`

Valor de texto.

Comprimento mínimo: 2. Comprimento máximo: 64.

**lipSyncUsage** `string`

Valor de texto.

Valores aceitos: "all", "none", "standard", "pro", "pro\_2".

**translationStatuses** `array`

Lista de valores. Consulte o esquema de entrada completo para ver a estrutura dos itens.

Máximo de itens: 4.

**billingState** `string`

Valor de texto.

Valores aceitos: "all", "charged", "refunded", "refund\_pending".

**fromDate** `string`

Valor de texto.

Formato: "date". Padrão: `^(?:(?:\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** `string`

Valor de texto.

Formato: "date". Padrão: `^(?:(?:\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** `integer`

Valor inteiro.

Mínimo: 1. Máximo: 100000. Valor padrão: 1.

**pageSize** `integer`

Valor inteiro.

Mínimo: 1. Máximo: 100. Valor padrão: 25.

> [accordion] Esquema de entrada completo
>
> O JSON Schema abaixo preserva os nomes exatos dos campos, tipos aninhados, valores padrão, limites e valores aceitos expostos pela descoberta. Regras adicionais entre campos são listadas nas notas da operação.
>
> ```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
> }
> ```

## Exemplos de requisição

Substitua os identificadores de recursos e as chaves de mídia dos exemplos pelos valores retornados para sua conta. Mantenha o identificador da requisição ao tentar novamente a mesma alteração.

```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)
```

## Resposta

Uma primeira execução bem-sucedida retorna HTTP 200 com o resultado da operação em data. Uma repetição pode retornar o estado salvo da requisição. O exemplo mostra uma resposta aceita, não todos os campos opcionais.

Retorna linhas paginadas de uso de tradução ou projeto, filtros normalizados e totais de minutos de todas as linhas correspondentes.

```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 do resultado

| Campo | Descrição |
| - | - |
| `data.exportedAt` | Momento em que o resultado foi produzido, como timestamp Unix em milissegundos. |
| `data.scope` | user para uma conta pessoal ou team para uma equipe própria ou da qual a conta participa. |
| `data.plan` | Plano do proprietário do espaço de trabalho. |
| `data.view` | translation ou project, conforme a visualização solicitada. |
| `data.filters` | Filtros aplicados normalizados; a paginação é retornada separadamente. |
| `data.pagination.page` | Página retornada após aplicar o intervalo de páginas disponível. |
| `data.pagination.pageSize` | Número de linhas por página. |
| `data.pagination.totalItems` | Número total de linhas correspondentes antes da paginação. |
| `data.pagination.totalPages` | Número de páginas; pelo menos uma, mesmo para um resultado vazio. |
| `data.totals.translationBaseMinutes` | Minutos de tradução base cobrados nas linhas correspondentes. |
| `data.totals.lipSyncExtraMinutes` | Minutos adicionais de sincronização labial Standard cobrados. |
| `data.totals.lipSyncProExtraMinutes` | Minutos adicionais de sincronização labial Pro cobrados. |
| `data.totals.lipSyncPro2ExtraMinutes` | Minutos adicionais de sincronização labial Pro 2 cobrados. |
| `data.totals.totalChargedMinutes` | Total de minutos cobrados antes dos reembolsos. |
| `data.totals.refundedMinutes` | Minutos reembolsados. |
| `data.totals.netUsedMinutes` | Minutos cobrados menos minutos reembolsados. |
| `data.rows` | Linhas de tradução na visualização de traduções ou agregados de projetos na visualização de projetos. |
| `data.rows[].projectId` | Identificador do projeto. |
| `data.rows[].projectName` | Nome de exibição do projeto. |
| `data.rows[].workId` | Identificador do trabalho, presente na visualização de traduções. |
| `data.rows[].translatedVersionId` | Identificador da versão traduzida, presente na visualização de traduções. |
| `data.rows[].sourceLanguage` | Idioma de origem. |
| `data.rows[].targetLanguage` | Idioma de destino na visualização de traduções. |
| `data.rows[].startedAt` | Marcação de tempo do início da tradução em milissegundos, na visualização de traduções. |
| `data.rows[].endedAt` | Marcação de tempo opcional do fim da tradução/sincronização labial em milissegundos, na visualização de traduções. |
| `data.rows[].startedByUserId` | Identificador opcional da conta que iniciou a operação, na visualização de traduções. |
| `data.rows[].translationStatus` | in\_progress, completed, failed ou timed\_out na visualização de traduções. |
| `data.rows[].lipSyncUsage` | none, standard, pro ou pro\_2 na visualização de traduções. |
| `data.rows[].lipSyncStatus` | not\_used, in\_progress, completed, failed ou timed\_out na visualização de traduções. |
| `data.rows[].runNumber` | Número da execução de tradução neste projeto e idioma de destino, na visualização de traduções. |
| `data.rows[].createdAt` | Marcação de tempo de criação do projeto em milissegundos, na visualização de projetos. |
| `data.rows[].targetLanguages` | Idiomas de destino representados pelo agregado do projeto na visualização de projetos. |
| `data.rows[].runCount` | Quantidade de execuções de tradução correspondentes do projeto, na visualização de projetos. |
| `data.rows[].translationSummary` | Contagens na visualização de projetos: inProgress, completed, failed, timedOut e retryCount. |
| `data.rows[].lipSyncSummary` | Contagens na visualização de projetos: inProgress, completed, failed, timedOut, retryCount e notUsed. |
| `data.rows[].totalChargedMinutes` | Total de minutos cobrados na linha antes dos reembolsos. |
| `data.rows[].refundedMinutes` | Minutos reembolsados na linha. |
| `data.rows[].netUsedMinutes` | Minutos cobrados na linha menos reembolsos. |
| `data.rows[].billingState` | charged, refunded ou refund\_pending. |

## Notas da operação

* view tem translation como padrão, page tem 1 e pageSize tem 25; pageSize não pode exceder 100.
* Os filtros de data usam YYYY-MM-DD e comparam a data de início da tradução em Europe/Paris. fromDate não pode ser posterior a toDate.
* project pesquisa nomes e IDs de projetos sem diferenciar maiúsculas de minúsculas. translatedVersionId corresponde a IDs de versão por substring na visualização translation e é ignorado na visualização project.
* Os totais abrangem todas as linhas de tradução correspondentes antes da paginação. A visualização project agrega essas linhas por projeto.
* As linhas públicas omitem os endereços de e-mail dos usuários que iniciaram a ação e as mensagens brutas de erro de processamento.

## Uso

Cada chamada bem-sucedida consome uma chamada mensal da API/MCP. Os créditos de mídia e as cotas de geração da própria operação também se aplicam.

## Erros

| Status HTTP | Código | Significado ou recuperação |
| - | - | - |
| 400 | `CREDENTIAL_IN_QUERY` | Foram fornecidas credenciais em um parâmetro de consulta access\_token ou api\_key. Envie as credenciais nos cabeçalhos. |
| 400 | `VALIDATION_ERROR` | O objeto JSON contém um campo não compatível, um valor inválido ou um argumento obrigatório ausente. |
| 401 | `API_KEY_EXPIRED` | A chave de API expirou. |
| 401 | `INVALID_API_KEY` | Forneça uma chave de API válida e dentro do prazo de validade. |
| 401 | `INVALID_CREDENTIAL` | O cabeçalho Authorization está malformado ou entra em conflito com x-api-key. |
| 401 | `MISSING_CREDENTIAL` | Nenhuma credencial utilizável foi fornecida no cabeçalho, ou ela excedeu 4096 caracteres. |
| 401 | `USER_NOT_FOUND` | A conta da credencial não existe mais. |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | O usuário da credencial pertence a mais de uma equipe, portanto o contexto de cobrança é ambíguo. |
| 403 | `INSUFFICIENT_SCOPE` | Conceda todas as permissões necessárias ou escolha outra credencial. |
| 403 | `INTEGRATION_PLAN_UNSUPPORTED` | Não foi possível verificar os limites de integração da conta. |
| 403 | `SUBSCRIPTION_REQUIRED` | Use uma assinatura paga ativa. |
| 403 | `TEAM_MEMBERSHIP_INVALID` | O vínculo atual da conta com a equipe não corresponde ao espaço de trabalho desta conexão. Atualize o vínculo de membro e reconecte. |
| 403 | `TEAM_OWNER_NOT_FOUND` | Não foi possível encontrar a conta efetiva do proprietário da equipe. |
| 404 | `ACCOUNT_NOT_FOUND` | Não foi possível encontrar a conta ou a conta do espaço de trabalho ativo. |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Aguarde a renovação do limite mensal ou mude de plano. |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Aguarde o prazo de Retry-After, quando presente, e aumente progressivamente o intervalo entre as tentativas. |
| 500 | `INTERNAL_ERROR` | Verifique o estado da requisição salva e o histórico do recurso antes de decidir repetir uma alteração. |
| 503 | `SERVER_RESTARTING` | O servidor está reiniciando. Tente novamente em breve e mantenha o mesmo identificador de requisição para uma alteração. |

```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.