Dataset Export Async

Queue a dataset export with a webhook to receive the result asynchronously.

This endpoint initiates an asynchronous data export process. The export is processed in the background, and once complete, your webhook will be called with the results.

Request Flow

1. Submit your export request with dataset query and webhook URL
2. Receive immediate 201 response confirming the export was queued
3. Export is processed asynchronously (may take several minutes for large datasets)
4. Your webhook is called when the export completes

Webhook Response Format

Once the export is complete, your webhook will receive a POST request with this payload:

1
{
2
  queryUUID: string         // Unique identifier for this export request
3
  name: string             // The name you provided for this export
4
  format: 'csv' | 'jsonl' // The format you requested
5
  payload: DatasetPayload  // The original query payload you submitted
6
  hmacSignature: string    // HMAC signature for verification (see below)
7
  gcsBlob: {              // Information about the exported file
8
    url: string           // Signed download URL (valid for 30 days)
9
    expires: string       // ISO date string when URL expires
10
    timeTakenMs: number   // Processing time in milliseconds
11
    numberRows: number    // Number of rows in the exported data
12
  }
13
  requestedOn: Date       // When the export was originally requested
14
  completedOn: Date       // When the export was completed
15
}

HMAC Signature Verification

To verify the authenticity of webhook calls, compute the HMAC signature of the original request payload using your API key and compare it to the hmacSignature field in the webhook response.

Node.js Example:

1
const crypto = require('crypto');
2
3
// Verify webhook authenticity
4
function verifyWebhook(originalPayload, receivedSignature, apiKey) {
5
  const hmac = crypto.createHmac('sha256', apiKey);
6
  hmac.update(JSON.stringify(originalPayload));
7
  const computedSignature = hmac.digest('hex');
8
  return computedSignature === receivedSignature;
9
}
10
11
// Usage in your webhook handler
12
app.post('/your-webhook', (req, res) => {
13
  const { hmacSignature, payload } = req.body;
14
  const isValid = verifyWebhook(payload, hmacSignature, 'your-api-key');
15
  
16
  if (!isValid) {
17
    return res.status(401).send('Unauthorized');
18
  }
19
  
20
  // Process the webhook...
21
  res.status(200).send('OK');
22
});

Error Handling

• 400 Bad Request: Invalid webhook URL (must be HTTPS, no localhost/private IPs)
• 403 Forbidden: Invalid API key or insufficient permissions
• If the export fails during processing, your webhook will not be called

Requirements

• Valid API key in x-api-key header
• QueryBuilder product subscription OR query must include a report tag filter
• Webhook URL must be HTTPS and publicly accessible (no localhost/private networks)
• Your webhook endpoint should respond with 2xx status to confirm receipt

Important Notes

• The download URL expires in 30 days - ensure you download the file promptly
• Large exports may take several minutes to complete
• The queryUUID can be used to match requests to responses for tracking
• Files are compressed with gzip for efficient transfer