# Activity logs

Programmatically access your account's security history.

The [Activity Logs API](https://docs.stripe.com/api/v2/iam/activity-logs.md?api-version=2026-04-22.preview) provides programmatic access to your account’s security history. Use it to retrieve detailed logs of security-related activities across your Stripe account, including API key management, user invitations, and role changes.

With the Activity Logs API, you can:

- Monitor API key lifecycle events for security auditing.
- Track user access changes and role modifications.
- Create custom alerting systems for suspicious activities.
- Integrate activity data with your security information and event management (SIEM) system.

## Get started

Authenticate requests to the Activity Logs API using your [secret API key](https://docs.stripe.com/keys.md). Include the `Stripe-Version: 2026-04-22.preview` header in all requests.

## Tracked action types

The following sections describe the types of security events the Activity Logs API tracks.

### API key actions

- `api_key_created` - When a new API key is created
- `api_key_deleted` - When an API key is deleted
- `api_key_updated` - When an API key is modified
- `api_key_viewed` - When an API key’s secret is viewed

### User invitation actions

- `user_invite_created` - When a user invitation is sent
- `user_invite_deleted` - When a user invitation is revoked
- `user_invite_accepted` - When a user accepts an invitation

### User role actions

- `user_roles_updated` - When user roles are modified
- `user_roles_deleted` - When user roles are removed

> User role actions don’t include SSO and SCIM access updates.

Availability for these action types begins April 1, 2026. Stripe retains activity logs for 6 months.

## Access your activity

Each Activity Log object contains details about the security event, including the actor, timestamp, affected resources, and contextual metadata.

Use the [List activity logs](https://docs.stripe.com/api/v2/iam/activity-logs/list.md?api-version=2026-04-22.preview) endpoint to retrieve a paginated list of activity logs. Filter results by action group or specific action types to narrow your search.

The response returns results in ascending order by the `created` timestamp. Events appear in a list response 10 minutes after they occur.

### Pagination

The list response always includes `next_page_url`, even at the end of the available logs. Store the URL and use it to poll for new events for up to 10 days, after which you must restart pagination from the beginning.

The page token must be used with the same filters as the original request. Changing filters while reusing a page token returns a `400` error with `invalid_fields`.

## Use cases

You can use your activity detail to help with the following business needs:

- **Security monitoring**: Build automated alerts for sensitive account changes. Poll the list endpoint to detect unexpected API key creation, unusual role changes, or access from unfamiliar actors.
- **Compliance reporting**: Export activity logs to generate audit reports for compliance frameworks such as SOC 2 or PCI DSS. Each log entry includes timestamps, actor details, and affected resource information.

## Related resources

- [Activity Logs API reference](https://docs.stripe.com/api/v2/iam/activity-logs.md?api-version=2026-04-22.preview)
- [Platform security](https://docs.stripe.com/security.md)
- [Release phases](https://docs.stripe.com/release-phases.md)