Audit Logs API

Note: audit logging is available on request for enterprise customers.

The Audit Logs API lets you download your company's audit logs programmatically, using scoped API tokens. It's useful for exporting logs to a SIEM or automating compliance reporting.

Audit logs record who did what in your company's Flourish account — logins, visualization edits, data downloads, admin changes and more. See Audit events for the event structure and the full list of event types.

You don't have to use the API: if you'd rather not integrate against it, your Flourish support contact can provide your logs instead.

Create an API token

Only a company admin can manage API tokens, and only when audit logging is enabled for the company.

1. Sign in and go to the company settings page.
2. Find the API tokens section.
3. Click Create token, give it a name, and select the audit_log:read scope.
4. Copy the token immediately — it is shown only once. Flourish stores only a hash of the token (plus a short public token ID, for identification), so it cannot be retrieved again. If you lose a token, delete it and create a new one.

The same section lists your existing tokens — name, token ID, scopes, created date and last used date — and lets you delete a token. Deleting a token invalidates it immediately: any request using it gets a 401 response.

Restrict tokens by IP (optional)

You can optionally restrict API access to an allowlist of IP ranges. IP restrictions apply to all of your company's tokens, not per token.

1. In the API tokens section, click Add IP restrictions (or Edit IP restrictions).

2. Enter CIDR ranges, one per line (IPv4 or IPv6), for example:

   203.0.113.0/24
   2001:db8::/32
   

3. Save.

Tokens can then only be used from IPs inside the allowlist — a call from any other IP gets a 403 response. Saving an empty list clears the restriction and allows any IP again.

Ranges are validated and canonicalized on save: an invalid CIDR is rejected, and trailing host bits are normalized (for example, 10.0.0.5/24 becomes 10.0.0.0/24).

Authentication

A token is scoped to a single company when it's created, so the audit log endpoints take no company ID — the company is derived from the token. Send the token as a bearer header on every request:

Authorization: Bearer <token>

List and download log files

GET https://app.flourish.studio/api/audit-logs

Returns a page of audit log files for a date range. Each file comes with a short-lived pre-signed download URL.

Query parameters

Parameter	Required	Description
from	yes	Inclusive start date, YYYY-MM-DD (UTC).
to	yes	Inclusive end date, YYYY-MM-DD (UTC). Must not be in the future.
url_expiry_seconds	no	Lifetime of the pre-signed URLs, in seconds. Defaults to the server cap (900 seconds = 15 minutes) and may not exceed it.
continuation	no	Pagination token from a previous response.

Constraints:

• from must not be after to.
• The date range of a single request may not exceed 31 days. Logs are kept for at least 365 days — to cover a longer period, make multiple requests.
• Dates must be real calendar dates — for example, February 29th in a non-leap year is rejected.

Example

curl -s 'https://app.flourish.studio/api/audit-logs?from=2026-04-15&to=2026-04-20' \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "files": [
    {
      "key": "data/year=2026/month=04/day=15/log-1.gz",
      "size": 102400,
      "last_modified": "2026-04-15T12:00:00.000Z",
      "url": "https://<bucket>.s3.amazonaws.com/...&X-Amz-Signature=...",
      "expires_at": "2026-04-15T12:15:00.000Z"
    }
  ],
  "continuation": "<token, present only if more pages remain>"
}

Download each file from its url before expires_at. Files are gzipped (.gz).

Pagination

Up to 1000 files are returned per page. If the response includes a continuation value, pass it back as the continuation query parameter to fetch the next page. When it is absent, you have all the files for the requested range.

Event schema

GET https://app.flourish.studio/api/audit-logs/schema

Returns a machine-readable OpenAPI document describing the structure of the events inside the log files. It uses the same audit_log:read authentication, and is useful for building a parser. See Audit events for details.

Errors

Status	Meaning
400	Bad or missing dates, date range too large, or invalid url_expiry_seconds or continuation.
401	Missing or malformed Authorization header, or an invalid or deleted token.
403	Token lacks the required scope, audit logging is not enabled for the company, or the request IP is outside the allowlist.
500	Server or storage-side problem.

Notes

• Self-auditing: token creation and deletion, and IP restriction changes, are recorded as ADMINISTRATION events. Every call to GET /api/audit-logs is recorded as a DATA_DOWNLOADED event, with the outcome PERMITTED, DENIED or FAILED.
• Token storage: Flourish keeps only a hash of each token plus a short public token ID. Store the full token securely on your side.
• All dates are interpreted in UTC.