S3 and BI exports

Use Insights > Analytics > Export data to prepare a CSV or JSON file, download it, or connect your private Amazon S3 bucket for manual and automatic delivery. The same setup is available from Developer > Integrations > Configure S3 exports. Exports are available in both Test and Live Spaces without a separate export fee. AWS storage and transfer charges remain your responsibility.

Dataset: event-daily-v1

One row represents one UTC day, event key and historical event outcome.

No customer identifiers, profiles, context payloads, wallet balances, credentials or billing records are included. Do not sum distinct-customer counts across rows to obtain a global unique count. Counts are decimal strings in JSON to preserve integer precision. CSV quotes all values and prefixes potentially executable spreadsheet formulas with an apostrophe; JSON preserves event keys unchanged.

Exports reflect currently retained events, not every incoming HTTP attempt. Requests rejected before an event is recorded do not appear here. Late events, retention and customer erasure can change a previous day's results. Re-fetch and replace recent daily partitions instead of appending them blindly. These exports are not immutable backups or billing evidence; they are independent of the interactive Analytics page's current event filters and date selection.

Choose 1 to 90 completed UTC days. Today is excluded. Empty periods return a CSV header or an empty JSON array. A request is limited to 10,000 rows and 2 MiB; larger exports fail explicitly instead of silently truncating. Shorten the range if it is too large or takes too long. Automatic S3 delivery uses the same limits.

BI access

Create a dedicated server key in API access with Export analytics (analytics:read) only. This scope does not grant customer reads or writes. Existing keys do not gain the scope automatically. Keep the key in your BI tool's protected credentials or a backend secret store. Do not put it in query strings, client-side dashboards or shared reports.

GET https://api.perkamo.com/v1/exports/events?start_date=2026-09-01&end_date=2026-09-07&format=csv
x-perkamo-api-key: YOUR_READ_ONLY_KEY

Parameters start_date and end_date are required ISO dates, inclusive. format is csv (default) or json. The API key determines the Space; do not send a Space identifier. Client/browser tokens are not supported. Downloads have Cache-Control: no-store, a filename, X-Export-Schema and X-Export-Rows headers. The rate limit is six requests per minute per key; stop on 429 and honor retry guidance. Revoke the key in Console to disconnect the BI integration.

For Power BI or another HTTP-capable reporting tool, configure a Web/HTTP source with the URL and API-key header, then parse the CSV or JSON body. Scheduled refresh must use your tool's secure gateway or your own backend job. This is an HTTP dataset, not a native Power BI, Tableau or warehouse connector.

Connect Amazon S3

An owner or admin outside impersonation can configure one S3 connection per Space. Viewers can download and inspect delivery status but cannot configure credentials, change a schedule or upload data.

1. Open S3 & schedule in the export dialog.
2. Enter the bucket name, its AWS region and an optional folder prefix, such

as exports/. Use a private general purpose S3 bucket in a standard AWS region.

1. Enter a dedicated IAM access key ID and secret access key. Expand **AWS

permission policy** for a policy scoped to this Space's export folder.

1. Choose the interval and CSV or JSON, then select Connect and verify.

Verification writes a small connection-check JSON file to the folder. It contains no customer data and remains in your bucket. Both credential fields are encrypted and cannot be retrieved through the Console. When editing a connection, leave both credential fields empty to keep the saved keys. Enter both fields to replace them. A failed connection check preserves the previous working settings.

Keep S3 Block Public Access enabled. Grant the IAM identity s3:PutObject only within the export folder. Buckets encrypted with your own KMS key may need additional KMS permissions. Perkamo uses the bucket's encryption configuration. It does not need permission to list, read or delete your existing objects. Custom S3-compatible endpoints, temporary session credentials, directory buckets and AWS China or GovCloud regions are not supported by this connector. See AWS bucket guidance and AWS PutObject for the underlying bucket and permission requirements.

Automatic delivery

The connection summary shows the next scheduled time. Schedules are checked every minute; actual delivery time also depends on service availability and queue capacity. Each delivery creates a unique file under <prefix>perkamo/<space-id>/event-daily-v1/<start>_<end>/<export-id>.csv (or .json). Existing objects are not overwritten. After a service interruption, the latest completed period is exported; missed historical periods are not backfilled. Use manual delivery to fill a missing period or refresh data after late events.

Recent deliveries shows the latest ten attempts, with date ranges, file original destination buckets, paths, row counts and outcomes. History is retained for 90 days, including after you change the connection's bucket. A failed or unconfirmed run does not pause future scheduled exports. If delivery is unconfirmed, inspect that file in your bucket before sending again. Perkamo does not automatically retry an uncertain upload. Export files are not retained by Perkamo.

Set the interval to Off (manual delivery) to pause automatic exports while keeping the connection. Disconnect S3 stops delivery and removes saved credentials and delivery history. Files in your bucket or BI system follow your own retention policy; later Perkamo customer erasure does not delete those copies.