Cosmoner Docs
Guides

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

FieldWhat it says
ActionWhat was asked for, such as app.deploy, member.role_update or database.delete
WhoThe member or service account, by name and email as they were at the time
Signed in withThe control panel, an API key (named) or the CLI
TargetThe resource the change was aimed at, by the name it had before the change
Fields sentThe names of the settings included in the request
IP addressThe address the request came from
WhenThe 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.deploy means 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 the app.deployed and app.failed webhook 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.

On this page