Result exports to Amazon S3, Google Cloud Storage and BigQuery

Each hour or each UTC day, an export writes the window’s results as gzip-compressed JSON Lines to an Amazon S3 or Google Cloud Storage bucket, or loads them into a BigQuery table partition. Your warehouse reads them like any other source, with no polling loop. You grant our export identity write access to the bucket or dataset; you never share keys or passwords. Every key, bucket, account id and role on this page is a placeholder.

What is exported

Data set	Rows	Window by	Same fields as
`tasks`	Every task of the account that finished as `COMPLETED` or `FAILED`	`completedAt`	`GET /v1/async/task/{id}` and the webhook
`monitor_results`	Every scored answer of every monitor of the account	`ranAt`	`GET /v1/monitors/{id}/results?includeEvidence=true`

Tasks submitted with any of the account’s keys, from the Playground and by monitors are all included. A window holds exactly the rows whose time falls in [windowStart, windowEnd). Delivery timing. A window is due 10 minutes after it closes, so charges settled at the boundary are in it. Due windows are picked up by a job that runs every 15 minutes, so delivery normally starts 10 to 25 minutes after the window closes.

Set up an export

Read your export identity

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 names your folder and your tables. Every path and table we write carries it, so several querying.ai accounts can share one bucket or dataset and each writes only its own files. Grant the identity your response shows, not the placeholder above.

Grant access

Grant the identity access to your destination. See Grant access for S3, Cloud Storage and BigQuery.

Create the export

POST /v1/exports checks the grant and saves the export. See Create the export.

Watch the first delivery

GET /v1/exports/{id}/runs lists each window and its status. See Delivery history.

Grant access

Amazon S3

Create an IAM role in your AWS account that our Google identity can assume. Use the trustPolicy from the identity response as the role’s trust policy. It accepts only our export identity, and only with your account’s session name:

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

Attach a permissions policy that lets the role write under your prefix:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "s3:PutObject",
    "Resource": "arn:aws:s3:::acme-geo/querying/*"
  }]
}

If the bucket encrypts with a customer-managed KMS key, also allow kms:GenerateDataKey on that key.

Google Cloud Storage

Grant the export service account Storage Object User (roles/storage.objectUser) on the bucket. It creates the files and replaces them when a window is sent again.

gcloud storage buckets add-iam-policy-binding gs://acme-geo \
  --member="serviceAccount:querying-export@example-project.iam.gserviceaccount.com" \
  --role="roles/storage.objectUser"

To limit the grant to your folder, add an IAM condition on resource.name.startsWith("projects/_/buckets/acme-geo/objects/querying/acct_3f9a1c2b7d4e/").

BigQuery

Grant the export service account BigQuery Data Editor (roles/bigquery.dataEditor) on the dataset. We run the load jobs in our own project, so loading costs you nothing; you pay only for storage and the queries you run.

bq add-iam-policy-binding \
  --member="serviceAccount:querying-export@example-project.iam.gserviceaccount.com" \
  --role="roles/bigquery.dataEditor" acme-analytics:geo_raw

Create the export

Use an API key without an engine scope: an export carries every result of the account, so a key limited to some engines gets 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"
  }'

Field	Required	Description
`destination.type`	Yes	`s3`, `gcs` or `bigquery`.
`destination.bucket`	S3, GCS	The bucket name.
`destination.prefix`	No	Folder inside the bucket, up to 256 characters, relative (no leading `/`, no `.` or `..` segments). A trailing `/` is added.
`destination.region`	S3	The bucket’s AWS region, such as `us-east-1`.
`destination.roleArn`	S3	The role from Grant access, `arn:aws:iam::<account>:role/<name>`.
`destination.projectId`, `destination.datasetId`	BigQuery	The Google Cloud project and dataset.
`interval`	No	`hourly` or `daily` (default). Fixed for the life of the export.
`data`	No	`tasks`, `monitor_results` or both (default).
`startAt`	No	ISO 8601 time, not in the future and at most 30 days back. The first window is the one containing it. Default: now.

Before saving, the export proves the grant. For S3 and Cloud Storage it writes <prefix><accountKey>/_querying/connection-check.json; for BigQuery it reads the dataset and records its location. If the check fails, nothing is saved. An account can have up to 10 exports. The response is 201 with the export:

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

For S3 and Cloud Storage, destination echoes the bucket settings and adds path, the folder your files land in, such as s3://acme-geo/querying/acct_3f9a1c2b7d4e/ or gs://acme-geo/querying/acct_3f9a1c2b7d4e/. nextWindowStart is the start of the next window to be planned.

Errors

Status	Code	Cause
`400`	`VALIDATION_ERROR`	Invalid JSON or a field out of range. The message names the field, such as `destination.region: region is the bucket's AWS region, e.g. us-east-1`.
`403`	`KEY_SCOPE`	The API key is limited to some engines.
`409`	`EXPORT_LIMIT`	The account already has 10 exports.
`422`	`EXPORT_DESTINATION_UNREACHABLE`	The connection check failed. The message carries the storage provider’s reason, usually a missing grant.
`502`	`EXPORT_CHECK_FAILED`	The destination could not be reached. Try again.
`503`	`EXPORTS_NOT_CONFIGURED`	Exports to this destination type are not available.

Files and tables

Files in S3 and 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

Directories follow Hive partitioning (dt=, and hour= for hourly exports), so Athena, BigQuery external tables and Spark read them as columns.
v1 is the schema version (schemaVersion on the export). A change that breaks a column ships as v2 beside it.
A window splits into parts of up to 100,000 rows, in time order.
_manifest.json is written last. Load a window once its manifest exists, and read the part list from it:

{
  "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 in the manifest equals the number of lines in its parts and the rows of the run in the delivery history. File names depend only on the window, so a re-sent window replaces the same objects.

BigQuery tables

BigQuery exports load into querying_tasks_v1_<accountKey> and querying_monitor_results_v1_<accountKey>, created on the first load and partitioned by completedAt or ranAt (by day, or by hour for hourly exports). Each window replaces its own partition, so a re-sent window never doubles. payload, response, sources and scoringContext are JSON columns:

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

Row schema (v1)

`tasks`

Field	Type	BigQuery type	Description
`id`	string	`STRING`	Task id.
`taskType`	string	`STRING`	Engine, such as `CHATGPT`.
`status`	string	`STRING`	`COMPLETED` or `FAILED`.
`priority`	integer	`INT64`	As submitted.
`idempotencyKey`	string or null	`STRING`	Your key, when you sent one.
`createdAt`, `completedAt`	timestamp	`TIMESTAMP`	UTC, microsecond precision.
`monitorId`	string or null	`STRING`	The monitor that ran it.
`creditsCharged`	decimal	`NUMERIC`	Credits charged for the task, with up to two decimals (for example `1.25`). `0` for a failed task. Read it as a decimal, not an integer.
`payload`	object	`JSON`	The payload as submitted.
`response`	object or null	`JSON`	The result as `GET /v1/async/task/{id}` returns it; `null` when the task failed.
`error`	string or null	`STRING`	The failure reason, starting with its code; `null` when completed.

`monitor_results`

Field	Type	BigQuery type	Description
`id`, `monitorId`, `taskId`	string	`STRING`	Result, monitor and task ids.
`engine`, `prompt`	string	`STRING`	What was asked where.
`mentioned`, `cited`	boolean	`BOOL`	Brand named; your domain cited.
`position`	integer or null	`INT64`	Character offset of the first brand mention.
`competitorHits`	string array	`STRING`, repeated	Competitors named in the answer.
`sources`	array	`JSON`	Citations as `{url, label, position}`.
`answerText`	string or null	`STRING`	The answer the score was read from.
`scoringContext`	object or null	`JSON`	The scoring definition at the time.
`latitude`, `longitude`	number or null	`FLOAT64`	The point asked from, for location monitors.
`ranAt`	timestamp	`TIMESTAMP`	UTC, microsecond precision.

Delivery history

Each window of each data set is one run. List them newest first:

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`	Meaning
`pending`	Waiting to be delivered, or waiting to retry after a failed attempt. `nextAttemptAt` says when.
`running`	Being delivered now.
`delivered`	Written. `rows`, `bytes`, `files` and `deliveredAt` are set.
`failed`	Eight attempts failed. Nothing more happens until you retry it.

Filter with status, data (tasks or monitor_results) and limit (1–200, default 50); pass nextCursor back as cursor for the next page.

Automatic retries. A failed attempt is retried after 15 minutes, then with the delay doubling up to 12 hours, eight attempts in all. error holds the storage provider’s reason, so a missing permission shows up here first.
Send a window again. POST /v1/exports/{id}/runs/{runId}/retry sends a window now: a failed one after you fix the grant, or a delivered one you want rewritten. It resets attempts and returns the run as pending. A run that is being delivered returns 409 EXPORT_RUN_RUNNING.
Export health. GET /v1/exports and GET /v1/exports/{id} add deliveredThrough (the end of the latest delivered window), failedRuns and retryingRuns (pending runs that already failed at least once).

Pause, resume and delete

PATCH /v1/exports/{id} with {"enabled": false} pauses an export. {"enabled": true} resumes it and catches up on the windows it missed, back to 30 days.
DELETE /v1/exports/{id} stops the export. Files and partitions already delivered stay in your storage.
Destination, interval and data sets cannot change. Create a new export and delete the old one.

Endpoints

Method and path	Purpose
`GET /v1/exports/identity`	The identity to grant and your account key
`POST /v1/exports`	Connect a destination
`GET /v1/exports`	List exports with delivery health
`GET /v1/exports/{id}`	One export
`PATCH /v1/exports/{id}`	Pause or resume
`DELETE /v1/exports/{id}`	Stop the export
`GET /v1/exports/{id}/runs`	Delivery history
`POST /v1/exports/{id}/runs/{runId}/retry`	Send a window again

An export you do not own returns 404 NOT_FOUND.

Get started

Core concepts

Answer engines

Search and web data

Request options

Research

GEO monitoring

Account and data

Result exports to Amazon S3, Google Cloud Storage and BigQuery

What is exported

Set up an export

Grant access

Amazon S3

Google Cloud Storage

BigQuery

Create the export

Errors

Files and tables

Files in S3 and Cloud Storage

BigQuery tables

Row schema (v1)

`tasks`

`monitor_results`

Delivery history

Pause, resume and delete

Endpoints

​What is exported

​Set up an export

​Grant access

​Amazon S3

​Google Cloud Storage

​BigQuery

​Create the export

​Errors

​Files and tables

​Files in S3 and Cloud Storage

​BigQuery tables

​Row schema (v1)

​tasks

​monitor_results

​Delivery history

​Pause, resume and delete

​Endpoints

What is exported

Set up an export

Grant access

Amazon S3

Google Cloud Storage

BigQuery

Create the export

Errors

Files and tables

Files in S3 and Cloud Storage

BigQuery tables

Row schema (v1)

`tasks`

`monitor_results`

Delivery history

Pause, resume and delete

Endpoints