> ## 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 histórico de transcrições

> Liste seus resultados salvos de transcrições. Use nextCursor como beforeHistoryId para recuperar resultados mais antigos.

Liste seus resultados salvos de transcrições. Use nextCursor como beforeHistoryId para recuperar resultados mais antigos.

```http theme={null}
POST https://api.voicecheap.ai/v1/actions/transcription_history_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: `transcription: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

**limit** `integer`

Valor inteiro.

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

**beforeHistoryId** `string`

Valor de texto.

Comprimento mínimo: 1. Comprimento máximo: 160. Padrão: `^[A-Za-z0-9_-]+$`.

> [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": {
>     "limit": {
>       "default": 30,
>       "type": "integer",
>       "minimum": 1,
>       "maximum": 100
>     },
>     "beforeHistoryId": {
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 160,
>       "pattern": "^[A-Za-z0-9_-]+$"
>     }
>   },
>   "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/transcription_history_list' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"limit":30}'
```

```javascript JavaScript theme={null}
const input = {
  limit: 30,
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/transcription_history_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/transcription_history_list",
    headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
    json={"limit": 30},
    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.

Um objeto paginado contendo resumos do histórico de transcrição pertencentes ao ator e nextCursor.

```json HTTP 200 theme={null}
{
  "data": {
    "items": [
      {
        "historyId": "history_20261016_001",
        "fileName": "interview.mp4",
        "createdAt": 1792152000000,
        "updatedAt": 1792152000000,
        "fileSizeBytes": 1048576,
        "fileSizeMb": 1,
        "durationSeconds": 60,
        "durationMinutes": 1,
        "mimeType": "video/mp4",
        "extension": "mp4",
        "detectedLanguage": "en",
        "status": "success",
        "keyterms": [
          "VoiceCheap"
        ]
      }
    ],
    "nextCursor": null
  }
}
```

## Campos do resultado

| Campo | Descrição |
| - | - |
| `data.items` | Array de resumos de metadados de transcrição; o conteúdo de saída é retornado pela ação history\_get correspondente. |
| `data.nextCursor` | Último historyId selecionado quando há mais itens; caso contrário, null. |

## Notas da operação

* Requer uma assinatura paga e a permissão da ação. O plano pessoal de ferramentas do usuário executor é verificado novamente na execução; as ferramentas salvas e as referências de envio pertencem a esse usuário, inclusive quando a credencial está associada a uma equipe.
* Uma ação bem-sucedida usa uma chamada mensal compartilhada de API/MCP. Beginner permite 500, Starter 5,000 e Creator 25,000 chamadas/mês; Pro, Scale e Enterprise não têm teto mensal. Os limites por minuto ainda se aplicam: 30, 60, 120, 180, 300 e 600, respectivamente. As cotas de geração das ferramentas são separadas.
* O padrão de limit é 30, e ele aceita números inteiros de 1 a 100. Os resultados são ordenados do mais recente ao mais antigo. Passe nextCursor como beforeHistoryId para a próxima página; null significa que não há página mais antiga.
* Os itens retornados são resumos pessoais salvos do histórico das ferramentas web. Eles diferem da coleção durável result\_list da integração; as ferramentas só podem salvar o histórico na medida do possível.
* Esta leitura não gera mídia nem consome o limite diário da ferramenta; ela usa uma chamada mensal de integração bem-sucedida.

## 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` | Os argumentos não atendem ao esquema da ação ou um argumento desconhecido foi fornecido. |
| 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` | A chave de API ou a conexão MCP não tem a permissão necessária para a ação. |
| 403 | `INTEGRATION_PLAN_UNSUPPORTED` | Não foi possível verificar os limites de integração da conta. |
| 403 | `PAID_SUBSCRIPTION_REQUIRED` | O ator autenticado não tem mais uma assinatura paga quando esta ação da ferramenta é executada. |
| 403 | `SUBSCRIPTION_REQUIRED` | Use uma assinatura paga ativa. |
| 403 | `TEAM_OWNER_NOT_FOUND` | Não foi possível encontrar a conta efetiva do proprietário da equipe. |
| 404 | `HISTORY_CURSOR_NOT_FOUND` | beforeHistoryId não identifica um cursor pertencente à conta nesta coleção de histórico. |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | As chamadas usadas e pendentes atingiram a cota mensal compartilhada de API/MCP. |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | A conta atingiu seu limite de integração por minuto; inspecione retryAfterSeconds. |
| 500 | `INTERNAL_ERROR` | Não foi possível ler o histórico salvo. |
| 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": ["transcription:read"]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.