> ## Documentation Index > Fetch the complete documentation index at: https://docs.querying.ai/llms.txt > Use this file to discover all available pages before exploring further. # Exportação de resultados para Amazon S3, Google Cloud Storage e BigQuery > Receba cada tarefa concluída e cada resposta pontuada dos monitores como arquivos JSON Lines por hora ou por dia no seu próprio bucket, ou como partições de uma tabela do BigQuery. A cada hora ou a cada dia UTC, uma exportação grava os resultados da janela como JSON Lines compactado com gzip em um bucket do Amazon S3 ou do Google Cloud Storage, ou os carrega em uma partição de uma tabela do BigQuery. Seu data warehouse os lê como qualquer outra fonte, sem loop de polling. Você concede à nossa identidade de exportação permissão de escrita no bucket ou no dataset; você nunca compartilha chaves nem senhas. Todas as chaves, buckets, IDs de conta e roles desta página são exemplos. ## O que é exportado | Conjunto de dados | Linhas | Janela por | Mesmos campos que | | - | - | - | - | | `tasks` | Cada tarefa da conta que terminou como `COMPLETED` ou `FAILED` | `completedAt` | [`GET /v1/async/task/{id}`](/pt/api-reference/get-task) e o webhook | | `monitor_results` | Cada resposta pontuada de cada monitor da conta | `ranAt` | [`GET /v1/monitors/{id}/results?includeEvidence=true`](/pt/api-reference/monitors/export-results) | Entram as tarefas enviadas com qualquer chave da conta, pelo Playground e pelos monitores. Uma janela contém exatamente as linhas cujo horário cai em `[windowStart, windowEnd)`. **Prazo de entrega.** Uma janela fica pronta 10 minutos depois de fechar, para que as cobranças liquidadas no limite entrem nela. As janelas prontas são coletadas por um job que roda a cada 15 minutos, então a entrega normalmente começa de 10 a 25 minutos depois que a janela fecha. ## Configure uma exportação **1. Consulte sua identidade de exportação** ```bash theme={"theme":"css-variables"} curl https://api.querying.ai/v1/exports/identity \ -H "Authorization: Bearer $QUERYING_API_KEY" ``` ```json theme={"theme":"css-variables"} { "success": true, "identity": { "accountKey": "acct_3f9a1c2b7d4e", "gcp": { "serviceAccount": "querying-export@example-project.iam.gserviceaccount.com" }, "aws": { "federatedPrincipal": "accounts.google.com", "audience": "117000000000000000001", "oaud": "querying-result-export", "roleSessionName": "querying-acct_3f9a1c2b7d4e", "trustPolicy": { "Version": "2012-10-17", "Statement": ["..."] } } } } ``` `accountKey` dá nome à sua pasta e às suas tabelas. Todo caminho e toda tabela que escrevemos o contém, então várias contas do querying.ai podem compartilhar um bucket ou dataset e cada uma escreve apenas os próprios arquivos. Autorize a identidade que a sua resposta mostra, não o exemplo acima. **2. Conceda acesso** Conceda à identidade acesso ao seu destino. Veja [Conceda acesso](#conceda-acesso) para S3, Cloud Storage e BigQuery. **3. Crie a exportação** `POST /v1/exports` verifica a permissão e salva a exportação. Veja [Crie a exportação](#crie-a-exportação). **4. Acompanhe a primeira entrega** `GET /v1/exports/{id}/runs` lista cada janela e o seu status. Veja [Histórico de entregas](#histórico-de-entregas). ## Conceda acesso ### Amazon S3 Crie na sua conta AWS uma role do IAM que nossa identidade do Google possa assumir. Use o `trustPolicy` da resposta de identidade como política de confiança da role. Ela aceita apenas nossa identidade de exportação, e apenas com o nome de sessão da sua conta: ```json theme={"theme":"css-variables"} { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": { "Federated": "accounts.google.com" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "accounts.google.com:aud": "117000000000000000001", "accounts.google.com:oaud": "querying-result-export", "sts:RoleSessionName": "querying-acct_3f9a1c2b7d4e" } } }] } ``` Anexe uma política de permissões que deixe a role escrever sob o seu prefixo: ```json theme={"theme":"css-variables"} { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": "s3:PutObject", "Resource": "arn:aws:s3:::acme-geo/querying/*" }] } ``` Se o bucket criptografa com uma chave KMS gerenciada pelo cliente, permita também `kms:GenerateDataKey` nessa chave. ### Google Cloud Storage Conceda à conta de serviço de exportação **Storage Object User** (`roles/storage.objectUser`) no bucket. Ela cria os arquivos e os substitui quando uma janela é reenviada. ```bash theme={"theme":"css-variables"} gcloud storage buckets add-iam-policy-binding gs://acme-geo \ --member="serviceAccount:querying-export@example-project.iam.gserviceaccount.com" \ --role="roles/storage.objectUser" ``` Para limitar a permissão à sua pasta, adicione uma condição do IAM em `resource.name.startsWith("projects/_/buckets/acme-geo/objects/querying/acct_3f9a1c2b7d4e/")`. ### BigQuery Conceda à conta de serviço de exportação **BigQuery Data Editor** (`roles/bigquery.dataEditor`) no dataset. Executamos os jobs de carga no nosso próprio projeto, então carregar não custa nada para você; você paga apenas o armazenamento e as consultas que executar. ```bash theme={"theme":"css-variables"} bq add-iam-policy-binding \ --member="serviceAccount:querying-export@example-project.iam.gserviceaccount.com" \ --role="roles/bigquery.dataEditor" acme-analytics:geo_raw ``` ## Crie a exportação Use uma chave de API sem escopo de mecanismo: uma exportação leva todos os resultados da conta, então uma chave limitada a alguns mecanismos recebe `403 KEY_SCOPE`. ```bash Amazon S3 theme={"theme":"css-variables"} curl -X POST https://api.querying.ai/v1/exports \ -H "Authorization: Bearer $QUERYING_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "destination": { "type": "s3", "bucket": "acme-geo", "region": "us-east-1", "roleArn": "arn:aws:iam::123456789012:role/querying-export", "prefix": "querying" }, "interval": "daily", "data": ["tasks", "monitor_results"] }' ``` ```bash Google Cloud Storage theme={"theme":"css-variables"} curl -X POST https://api.querying.ai/v1/exports \ -H "Authorization: Bearer $QUERYING_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "destination": { "type": "gcs", "bucket": "acme-geo", "prefix": "querying" }, "interval": "hourly", "data": ["tasks"] }' ``` ```bash BigQuery theme={"theme":"css-variables"} curl -X POST https://api.querying.ai/v1/exports \ -H "Authorization: Bearer $QUERYING_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "destination": { "type": "bigquery", "projectId": "acme-analytics", "datasetId": "geo_raw" }, "interval": "daily", "startAt": "2026-10-01T00:00:00Z" }' ``` | Campo | Obrigatório | Descrição | | - | - | - | | `destination.type` | Sim | `s3`, `gcs` ou `bigquery`. | | `destination.bucket` | S3, GCS | O nome do bucket. | | `destination.prefix` | Não | Pasta dentro do bucket, até 256 caracteres, relativa (sem `/` inicial, sem segmentos `.` ou `..`). Uma `/` final é adicionada. | | `destination.region` | S3 | A região AWS do bucket, como `us-east-1`. | | `destination.roleArn` | S3 | A role de [Conceda acesso](#amazon-s3), `arn:aws:iam:::role/`. | | `destination.projectId`, `destination.datasetId` | BigQuery | O projeto e o dataset do Google Cloud. | | `interval` | Não | `hourly` ou `daily` (padrão). Fica fixo durante toda a vida da exportação. | | `data` | Não | `tasks`, `monitor_results` ou ambos (padrão). | | `startAt` | Não | Horário ISO 8601, não no futuro e de no máximo 30 dias atrás. A primeira janela é a que o contém. Padrão: agora. | Antes de salvar, a exportação comprova a permissão. Para S3 e Cloud Storage, ela escreve `/_querying/connection-check.json`; para o BigQuery, lê o dataset e registra a sua localização. Se a verificação falhar, nada é salvo. Uma conta pode ter até 10 exportações. A resposta é `201` com a exportação: ```json theme={"theme":"css-variables"} { "success": true, "export": { "id": "6a1d0f3c-...", "destination": { "type": "bigquery", "projectId": "acme-analytics", "datasetId": "geo_raw", "location": "US", "tables": [ "acme-analytics.geo_raw.querying_tasks_v1_acct_3f9a1c2b7d4e", "acme-analytics.geo_raw.querying_monitor_results_v1_acct_3f9a1c2b7d4e" ] }, "interval": "daily", "data": ["tasks", "monitor_results"], "enabled": true, "schemaVersion": 1, "nextWindowStart": "2026-10-01T00:00:00.000Z", "createdAt": "2026-10-19T09:00:00.000Z", "deliveredThrough": null, "failedRuns": 0, "retryingRuns": 0 } } ``` Para S3 e Cloud Storage, `destination` repete as configurações do bucket e adiciona `path`, a pasta onde seus arquivos chegam, como `s3://acme-geo/querying/acct_3f9a1c2b7d4e/` ou `gs://acme-geo/querying/acct_3f9a1c2b7d4e/`. `nextWindowStart` é o início da próxima janela a ser planejada. ### Erros | Status | Código | Causa | | - | - | - | | `400` | `VALIDATION_ERROR` | JSON inválido ou um campo fora do intervalo. A mensagem indica o campo, como `destination.region: region is the bucket's AWS region, e.g. us-east-1`. | | `403` | `KEY_SCOPE` | A chave de API está limitada a alguns mecanismos. | | `409` | `EXPORT_LIMIT` | A conta já tem 10 exportações. | | `422` | `EXPORT_DESTINATION_UNREACHABLE` | A verificação de conexão falhou. A mensagem traz o motivo do provedor de armazenamento, geralmente uma permissão ausente. | | `502` | `EXPORT_CHECK_FAILED` | Não foi possível acessar o destino. Tente de novo. | | `503` | `EXPORTS_NOT_CONFIGURED` | Exportações para este tipo de destino não estão disponíveis. | ## Arquivos e tabelas ### Arquivos no S3 e no Cloud Storage ```text theme={"theme":"css-variables"} s3://acme-geo/querying/acct_3f9a1c2b7d4e/tasks/v1/dt=2026-10-08/part-00000.jsonl.gz s3://acme-geo/querying/acct_3f9a1c2b7d4e/tasks/v1/dt=2026-10-08/_manifest.json s3://acme-geo/querying/acct_3f9a1c2b7d4e/monitor_results/v1/dt=2026-10-08/hour=13/part-00000.jsonl.gz ``` * Os diretórios seguem o particionamento do Hive (`dt=`, e `hour=` em exportações por hora), então Athena, tabelas externas do BigQuery e Spark os leem como colunas. * `v1` é a versão do esquema (`schemaVersion` na exportação). Uma mudança que quebre uma coluna sai como `v2` ao lado. * Uma janela é dividida em partes de até 100.000 linhas, em ordem de tempo. * `_manifest.json` é escrito por último. Carregue uma janela quando o manifesto existir e leia dele a lista de partes: ```json theme={"theme":"css-variables"} { "schemaVersion": 1, "data": "tasks", "windowStart": "2026-10-08T00:00:00.000Z", "windowEnd": "2026-10-09T00:00:00.000Z", "rows": 20000, "files": [{ "key": "querying/acct_3f9a1c2b7d4e/tasks/v1/dt=2026-10-08/part-00000.jsonl.gz", "rows": 20000, "bytes": 1990096 }], "deliveredAt": "2026-10-09T00:16:02.114Z" } ``` `rows` no manifesto é igual ao número de linhas das partes e ao `rows` da execução no histórico de entregas. Os nomes dos arquivos dependem apenas da janela, então uma janela reenviada substitui os mesmos objetos. ### Tabelas do BigQuery Exportações para o BigQuery carregam em `querying_tasks_v1_` e `querying_monitor_results_v1_`, criadas na primeira carga e particionadas por `completedAt` ou `ranAt` (por dia, ou por hora em exportações por hora). Cada janela substitui a própria partição, então uma janela reenviada nunca duplica. `payload`, `response`, `sources` e `scoringContext` são colunas `JSON`: ```sql theme={"theme":"css-variables"} SELECT taskType, JSON_VALUE(payload.prompt) AS prompt, JSON_VALUE(response.text) AS answer FROM `acme-analytics.geo_raw.querying_tasks_v1_acct_3f9a1c2b7d4e` WHERE DATE(completedAt) = "2026-10-08" AND status = "COMPLETED"; ``` ## Esquema das linhas (v1) ### `tasks` | Campo | Tipo | Tipo no BigQuery | Descrição | | - | - | - | - | | `id` | string | `STRING` | ID da tarefa. | | `taskType` | string | `STRING` | Mecanismo, como `CHATGPT`. | | `status` | string | `STRING` | `COMPLETED` ou `FAILED`. | | `priority` | integer | `INT64` | Como enviado. | | `idempotencyKey` | string ou null | `STRING` | Sua chave, quando você enviou uma. | | `createdAt`, `completedAt` | timestamp | `TIMESTAMP` | UTC, precisão de microssegundos. | | `monitorId` | string ou null | `STRING` | O monitor que a executou. | | `creditsCharged` | decimal | `NUMERIC` | Créditos cobrados pela tarefa, com até duas casas decimais (por exemplo `1.25`). `0` para uma tarefa com falha. Leia como decimal, não como inteiro. | | `payload` | object | `JSON` | O payload como enviado. | | `response` | object ou null | `JSON` | O resultado como `GET /v1/async/task/{id}` o retorna; `null` quando a tarefa falhou. | | `error` | string ou null | `STRING` | O motivo da falha, começando pelo código; `null` quando concluída. | ### `monitor_results` | Campo | Tipo | Tipo no BigQuery | Descrição | | - | - | - | - | | `id`, `monitorId`, `taskId` | string | `STRING` | IDs do resultado, do monitor e da tarefa. | | `engine`, `prompt` | string | `STRING` | O que foi perguntado e onde. | | `mentioned`, `cited` | boolean | `BOOL` | Marca citada; seu domínio citado como fonte. | | `position` | integer ou null | `INT64` | Posição em caracteres da primeira menção à marca. | | `competitorHits` | string array | `STRING`, repetido | Concorrentes citados na resposta. | | `sources` | array | `JSON` | Citações como `{url, label, position}`. | | `answerText` | string ou null | `STRING` | A resposta da qual a pontuação foi lida. | | `scoringContext` | object ou null | `JSON` | A definição de pontuação naquele momento. | | `latitude`, `longitude` | number ou null | `FLOAT64` | O ponto de onde se perguntou, em monitores com localização. | | `ranAt` | timestamp | `TIMESTAMP` | UTC, precisão de microssegundos. | ## Histórico de entregas Cada janela de cada conjunto de dados é uma execução. Liste-as da mais recente para a mais antiga: ```bash theme={"theme":"css-variables"} curl "https://api.querying.ai/v1/exports/$EXPORT_ID/runs?status=failed" \ -H "Authorization: Bearer $QUERYING_API_KEY" ``` ```json theme={"theme":"css-variables"} { "success": true, "runs": [{ "id": "3c9e1b7a-...", "data": "tasks", "windowStart": "2026-10-08T00:00:00.000Z", "windowEnd": "2026-10-09T00:00:00.000Z", "status": "failed", "attempts": 8, "nextAttemptAt": null, "rows": null, "bytes": null, "files": [], "error": "S3 PutObject s3://acme-geo/... failed: HTTP 403 AccessDenied: Access Denied", "deliveredAt": null }], "nextCursor": null } ``` | `status` | Significado | | - | - | | `pending` | Aguardando entrega, ou aguardando nova tentativa depois de uma falha. `nextAttemptAt` diz quando. | | `running` | Sendo entregue agora. | | `delivered` | Gravada. `rows`, `bytes`, `files` e `deliveredAt` são preenchidos. | | `failed` | Oito tentativas falharam. Nada mais acontece até você reenviá-la. | Filtre com `status`, `data` (`tasks` ou `monitor_results`) e `limit` (1–200, padrão 50); passe `nextCursor` de volta como `cursor` para a próxima página. * **Novas tentativas automáticas.** Uma tentativa com falha é repetida após 15 minutos e depois com o intervalo dobrando até 12 horas, oito tentativas no total. `error` traz o motivo do provedor de armazenamento, então uma permissão ausente aparece aqui primeiro. * **Reenvie uma janela.** `POST /v1/exports/{id}/runs/{runId}/retry` envia uma janela agora: uma com falha depois que você corrige a permissão, ou uma entregue que você quer reescrever. Ele zera `attempts` e retorna a execução como `pending`. Uma execução que está sendo entregue retorna `409 EXPORT_RUN_RUNNING`. * **Saúde da exportação.** `GET /v1/exports` e `GET /v1/exports/{id}` adicionam `deliveredThrough` (o fim da última janela entregue), `failedRuns` e `retryingRuns` (execuções pendentes que já falharam pelo menos uma vez). ## Pausar, retomar e excluir * `PATCH /v1/exports/{id}` com `{"enabled": false}` pausa uma exportação. `{"enabled": true}` a retoma e recupera as janelas perdidas, até 30 dias atrás. * `DELETE /v1/exports/{id}` encerra a exportação. Os arquivos e partições já entregues ficam no seu armazenamento. * Destino, frequência e conjuntos de dados não podem mudar. Crie uma exportação nova e exclua a anterior. ## Endpoints | Método e caminho | Uso | | - | - | | [`GET /v1/exports/identity`](/pt/api-reference/exports/get-identity) | A identidade a autorizar e a chave da sua conta | | [`POST /v1/exports`](/pt/api-reference/exports/create-export) | Conectar um destino | | [`GET /v1/exports`](/pt/api-reference/exports/list-exports) | Listar exportações com a saúde das entregas | | [`GET /v1/exports/{id}`](/pt/api-reference/exports/get-export) | Uma exportação | | [`PATCH /v1/exports/{id}`](/pt/api-reference/exports/update-export) | Pausar ou retomar | | [`DELETE /v1/exports/{id}`](/pt/api-reference/exports/delete-export) | Encerrar a exportação | | [`GET /v1/exports/{id}/runs`](/pt/api-reference/exports/list-runs) | Histórico de entregas | | [`POST /v1/exports/{id}/runs/{runId}/retry`](/pt/api-reference/exports/retry-run) | Reenviar uma janela | Uma exportação que não é sua retorna `404 NOT_FOUND`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.