Audit Log
See who changed what in a project, when, and how they were signed in.
Every project keeps an audit log: a record of each change made to it, with who made the change, when, how they were signed in and what it was aimed at. Use it to answer questions like "who deleted that database?", "when did this member become an admin?" or "which API key deployed on Friday night?".
Open it under Audit log in your project, or read it with the Audit log API.
Who can read it
Project owners and admins. Developers and viewers cannot, in the control panel or through the API. See Team Roles.
An API key needs the audit-log:read scope, and the service account it belongs
to needs the admin role. The scope is read-only: nothing can write to the log
except the platform itself.
What an event records
| Field | What it says |
|---|---|
| Action | What was asked for, such as app.deploy, member.role_update or database.delete |
| Who | The member or service account, by name and email as they were at the time |
| Signed in with | The control panel, an API key (named) or the CLI |
| Target | The resource the change was aimed at, by the name it had before the change |
| Fields sent | The names of the settings included in the request |
| IP address | The address the request came from |
| When | The time the change was made |
A few things follow from how events are written:
- An event keeps its names. If the database, the API key or the member's account is deleted later, the event still says what it was called.
- An event records a request, not its outcome.
app.deploymeans a member asked for a deploy and the request was accepted. Whether the deploy then succeeded is on the app's deployments page, and in theapp.deployedandapp.failedwebhook events. - Only accepted changes are recorded. A request that was refused, for example for lack of permission, changed nothing and leaves no event.
- Values are not kept. An event lists which fields a request sent, never what they were set to, because they can be secrets. The exceptions are a handful of plain choices where the value is the point: the role a member was given, a plan or tier, a PHP version, a server power action, and the address an invitation was sent to.
What is recorded
Changes to what your project is made of:
- apps: creating, deploying, rolling back, resizing, changing settings and domains, deleting
- databases, Valkey instances, buckets, registries, servers and web hosting sites: creating, changing plans and settings, deleting
- domains, email domains, forwarders, SMTP credentials and email templates
- secrets and variables (by name, never by value)
- members, invitations and roles
- API keys, service accounts and access keys
- webhooks, integrations and resource groups
- payment methods, plans, agreements and billing responsibility
What is not recorded
- The data inside your resources. Rows in a database, files in a bucket or on a hosting site, keys in a cache and email you send are not in the audit log. That data also changes over SQL, SFTP, the S3-compatible API and SMTP, outside the control panel and the API, so a list of only some of those changes would look complete without being so.
- Reads. Viewing a page or listing resources through the API leaves no event.
- Changes the platform makes on its own, such as an automatic deploy after a push to your repository, a scheduled security update of a hosting site, or a resource paused over an unpaid invoice. No member made those changes, so the log has nobody to name.
- Deleting the project. The log is deleted with the project.
How long events are kept
Events are kept for 180 days and then deleted. Events cannot be edited or deleted by anyone in the project, whatever their role.
If you need a longer history, export the log on a schedule with the API and keep it in your own systems.
Exporting the log
The API returns events newest first, a page at a time:
curl -H "Authorization: Bearer $COSMONER_API_KEY" \
"https://api.cosmoner.com/v1/projects/$PROJECT_ID/audit-log?limit=100"Pass the nextCursor from one response as cursor on the next, until it is
null. Narrow the log with resource (for example member or app),
actorId, from and to. To pick up only what is new since your last export,
pass the time of the newest event you already have as from.
Treat action as text. New actions are added as the platform grows, and an
export that fails on one it has not seen before will stop on the day we ship a
feature.