API Reference
WS external-service/csv-generator

CSV generator

Combine one or more metric queries into a single CSV, returned as a signed S3 download URL.

Long-running export route that runs one or more metric queries, combines the results into a single CSV, and returns a signed S3 URL to download it. Use it for scheduled exports, BI ingestion, or anywhere a file beats a stream.

Signed URL expiry: the URL returned has a short expiry. Fetch the file promptly; you’ll need to issue a fresh export request to refresh.

Body parameters

FieldTypeRequiredDescription
csvFormat.columnsobject[]yesArray of column descriptors — see below
csvFormat.sortBynumber[]yesArray of column indices (integers into columns) to sort the CSV by — not an array of objects
csvFormat.rowFiltersstring[]yesNon-empty array of dimension enum strings (e.g. ["entity"], ["entity", "age"]) controlling which dimensions become rows
metricRequestsobject[]yesArray of metric request bodies — same shape as any standard metric route

csvFormat.columns shape

Each column has:

FieldTypeRequiredDescription
headingstringyesColumn label written to the CSV
metricIdstringnoBinds this column to a value in one of the metricRequests
fetchValuestringnoWhich field of the metric result to read (e.g. "sales_volume")
fieldstringnoSpecific field within complex metric results
filterobjectnoRestrict to a slice, e.g. { "taxonomy": "Products:Clothing" }

metricRequests shape

Each entry uses the standard metric body (start, end, entities, etc.) plus two optional labelling fields:

FieldTypeDescription
metricIdstringUsed to bind columns back to this request
namestringHuman-readable, used in the CSV

Multiple metric requests in one call are combined into a single CSV.

Example request

{
  "action": "external-service",
  "data": {
    "id": "req-csv-001",
    "route": "external-service/csv-generator",
    "body": {
      "csvFormat": {
        "columns": [
          { "heading": "Date" },
          { "heading": "Entries", "metricId": "entries-by-day", "fetchValue": "entries" }
        ],
        "sortBy": [0],
        "rowFilters": ["entity"]
      },
      "metricRequests": [
        {
          "metricId": "entries-by-day",
          "name": "Entries by day",
          "start": "2024-04-01T00:00:00.000Z",
          "end":   "2024-04-30T23:59:59.000Z",
          "entities": ["64a1b2c3d4e5f6a7b8c9d0e3"],
          "entityType": "location",
          "facets": ["segments"],
          "aggregationPeriod": "day"
        }
      ]
    }
  }
}

Example response

req-csv-001|0|0|{
  "body": [
    {
      "bucket": "aura-exports",
      "key": "exports/64a1b2c3d4e5f6a7b8c9d0e2/2024-04-15T10-15-00.csv",
      "signedUrl": "https://aura-exports.s3.amazonaws.com/exports/64a1b2c3d4e5f6a7b8c9d0e2/2024-04-15T10-15-00.csv?X-Amz-Signature=…"
    }
  ]
}

Fetch signedUrl directly with GET to retrieve the file. bucket + key are exposed if you have direct S3 access via your own AWS credentials.