Export your workspace's events

Last updated: November 3, 2026

Export your workspace's audit log events as a file, to keep your own records, answer an audit or feed a security tool. The export runs over the API, and the audit log gives you the command to start it.

Before you start

  • The audit log is part of the Enterprise plan. See Plans and what they include.

  • You need the Export events permission. The Admin role includes it; an admin can add it to another role in Roles.

  • You run the command from a terminal, or from a script or scheduled job, with a token that authenticates as you or as a service account.

Steps

  1. Open the workspace menu in the sidebar, choose Settings, then Audit Log under Security. Select Export at the top of the page. The Export events dialog shows a ready-made command for your workspace, covering the last month. Select Copy command.

  2. Close the dialog and open Access Tokens under Account.

  3. Select Create token, name it after what it is for, create it and copy the token. It is shown only once.

  4. In the command, replace <YOUR_TOKEN> with the token, and change start_date and end_date to the period you want, in ISO 8601 format (2026-09-01T00:00:00Z). Run it. The response is an export_id.

  5. Check the export with a GET to the same address followed by / and the export_id, with the same Authorization header. Repeat until status is completed.

     curl "https://app.layer.ai/backend/api/v1/workspaces/<WORKSPACE_ID>/events/exports/<EXPORT_ID>" \
       -H "Authorization: Bearer <YOUR_TOKEN>"
  6. Download the file from download_url before the time in expiration_date.

Result

A gzipped CSV file (.csv.gz) with one row per event and the columns timestamp, event_type, event_name, user_email, principal_id and data.

  • principal_id is the ID of the member, service account or agent the event was for. It is empty for a system event.

  • user_email is that member's email. A member who has since been suspended or removed from the workspace keeps their email on their past events, so exporting the same period twice gives the same file. It is empty for a system event and for a service account or agent; use principal_id to tell those apart.

  • data holds the event's details as JSON, the same details you see when you expand an event in the audit log.

Production tips

  • Export a whole organization. In a parent workspace, add "include_descendants": true to the request body to include the events of every child workspace. The file then has two more columns after principal_id, workspace_id and workspace_name.

  • Automate with a service account. A personal access token acts as you, with all your permissions, and stops working if you leave. For a scheduled export, create a service account with a role that has Export events and use its key instead. See Authentication in the developer docs.

  • Export in month-sized ranges. Schedule one export a month for the previous month, so each run is small and none overlap.

  • Feed a SIEM or data warehouse. Every row carries event_type and event_name, so you can route invitations and role changes to access reviews and asset exports to content tracking. Join on principal_id rather than user_email: it stays the same if a member changes their email, and it identifies service accounts and agents too.

  • Treat the token like a password. Keep it in a secret manager, give it an expiry, and revoke it in Access Tokens when the job is retired.

If something goes wrong

  • There is no Export button. Your role does not include Export events. Ask an admin to add it to your role, or to run the export.

  • The request returns 403. The token belongs to someone, or a service account, without Export events in this workspace. Use a token from an account that has it.

  • The request returns an error about end_date. end_date must be after start_date, and the range has a maximum length. Split a long period into monthly exports.

  • status is failed, or the download link has expired. Run the export again to get a new export_id and a fresh link.

  • A row has no user_email. The event was a system event (no principal_id either), or it was for a service account or agent, which has no email.

Related