Exportação de resultados para Amazon S3, Google Cloud Storage e 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}` e o webhook
`monitor_results`	Cada resposta pontuada de cada monitor da conta	`ranAt`	`GET /v1/monitors/{id}/results?includeEvidence=true`

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

Consulte sua identidade de exportação

curl https://api.querying.ai/v1/exports/identity \
  -H "Authorization: Bearer $QUERYING_API_KEY"

{
  "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.

Conceda acesso

Conceda à identidade acesso ao seu destino. Veja Conceda acesso para S3, Cloud Storage e BigQuery.

Crie a exportação

POST /v1/exports verifica a permissão e salva a exportação. Veja Crie a exportação.

Acompanhe a primeira entrega

GET /v1/exports/{id}/runs lista cada janela e o seu status. Veja 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:

{
  "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:

{
  "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.

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.

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.

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"]
  }'

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"]
  }'

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, `arn:aws:iam::<account>:role/<name>`.
`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 <prefix><accountKey>/_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:

{
  "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

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:

{
  "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_<accountKey> e querying_monitor_results_v1_<accountKey>, 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:

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:

curl "https://api.querying.ai/v1/exports/$EXPORT_ID/runs?status=failed" \
  -H "Authorization: Bearer $QUERYING_API_KEY"

{
  "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`	A identidade a autorizar e a chave da sua conta
`POST /v1/exports`	Conectar um destino
`GET /v1/exports`	Listar exportações com a saúde das entregas
`GET /v1/exports/{id}`	Uma exportação
`PATCH /v1/exports/{id}`	Pausar ou retomar
`DELETE /v1/exports/{id}`	Encerrar a exportação
`GET /v1/exports/{id}/runs`	Histórico de entregas
`POST /v1/exports/{id}/runs/{runId}/retry`	Reenviar uma janela

Uma exportação que não é sua retorna 404 NOT_FOUND.

Primeiros passos

Conceitos principais

Mecanismos de resposta

Busca e dados da web

Opções de requisição

Pesquisa

Monitoramento GEO

Conta e dados

Exportação de resultados para Amazon S3, Google Cloud Storage e BigQuery

O que é exportado

Configure uma exportação

Conceda acesso

Amazon S3

Google Cloud Storage

BigQuery

Crie a exportação

Erros

Arquivos e tabelas

Arquivos no S3 e no Cloud Storage

Tabelas do BigQuery

Esquema das linhas (v1)

`tasks`

`monitor_results`

Histórico de entregas

Pausar, retomar e excluir

Endpoints

​O que é exportado

​Configure uma exportação

​Conceda acesso

​Amazon S3

​Google Cloud Storage

​BigQuery

​Crie a exportação

​Erros

​Arquivos e tabelas

​Arquivos no S3 e no Cloud Storage

​Tabelas do BigQuery

​Esquema das linhas (v1)

​tasks

​monitor_results

​Histórico de entregas

​Pausar, retomar e excluir

​Endpoints

O que é exportado

Configure uma exportação

Conceda acesso

Amazon S3

Google Cloud Storage

BigQuery

Crie a exportação

Erros

Arquivos e tabelas

Arquivos no S3 e no Cloud Storage

Tabelas do BigQuery

Esquema das linhas (v1)

`tasks`

`monitor_results`

Histórico de entregas

Pausar, retomar e excluir

Endpoints