1. Docs
  2. Reference
  3. REST API Docs
  4. Audit Logs

Audit Logs

    Audit Logs provide a record of user actions and system events within Pulumi Cloud. The Audit Logs API allows you to retrieve and export audit log entries for compliance, security, and monitoring purposes.

    List Audit Log Events Handler V1

    ▼
    GET /api/orgs/{orgName}/auditlogs

    Lists audit log events for an organization. Either continuationToken or startTime is required. Supports filtering by event type and user.

    Request Parameters

    • orgName string path required
      The organization name
    • continuationToken string query optional
      Token for paginated result retrieval
    • endTime integer query optional
      Upper bound of the query range (unix timestamp)
    • eventFilter string query optional
      Filter audit logs by event type
    • format string query optional
      Response format: ‘json’ (default)
    • startTime integer query optional
      Returns entries older than this timestamp (unix timestamp)
    • userFilter string query optional
      Filter audit logs by username

    Responses

    200 OK
    Schema: ResponseAuditLogs
    • continuationToken string optional
      A continuation token for paginating through audit log results.
    • auditLogEvents array[AuditLogEvent] required
      The list of audit log events.
    • ↳ timestamp integer required
      Unix epoch timestamp (seconds) when the event occurred.
    • ↳ sourceIP string required
      IP address of the client that triggered the event.
    • ↳ event string required
      The audit event type identifier (e.g. ‘stack.update’, ‘member.added’).
    • ↳ description string required
      Human-readable description of the event.
    • ↳ user UserInfo required
      The user who performed the action.
    • ↳ tokenID string optional
      ID of the access token used to authenticate, if applicable.
    • ↳ tokenName string optional
      Name of the access token used to authenticate, if applicable.
    • ↳ reqOrgAdmin boolean optional
      Whether the action that triggered this event required the organization ADMIN role.
    • ↳ reqStackAdmin boolean optional
      Whether the action required stack admin privileges.
    • ↳ authFailure boolean optional
      Whether this event represents a failed authentication attempt.
    • ↳ actorName string optional
      Display name of the non-human actor (e.g. deploy token name) that triggered the event.
    • ↳ actorUrn string optional
      Pulumi URN of the non-human actor that triggered the event.
    Errors: 400 invalid query params 404 user not found

    Export Audit Log Events Handler V1

    ▼
    GET /api/orgs/{orgName}/auditlogs/export

    Exports audit log events for an organization in a downloadable format. Audit logs provide an immutable record of all user activity within the organization, including stack operations, member changes, and policy modifications. Results can be filtered by time range, event type, and user. Supported export formats are CSV and CEF (Common Event Format for SIEM integration). Pagination is supported via the continuationToken parameter.

    Important: This endpoint differs from other API endpoints:

    • The response is always gzip compressed. Use --compressed with curl or handle gzip decompression in your client.
    • The Content-Type: application/json response header is omitted.

    Note: In V1, startTime specifies the upper bound of the query range. Use the V2 endpoint for more intuitive time range semantics.

    Request Parameters

    • orgName string path required
      The organization name
    • continuationToken string query optional
      Token for paginated result retrieval
    • endTime integer query optional
      Upper bound of the query range (unix timestamp)
    • eventFilter string query optional
      Filter audit logs by event type
    • format string query optional
      Response format: ‘cef’ or ‘csv’ (defaults to csv)
    • startTime integer query optional
      Returns entries older than this timestamp (unix timestamp)
    • userFilter string query optional
      Filter audit logs by username

    Responses

    200 OK
    Errors: 400 Audit Logs is available only to organizations with an Enterprise subscription. 404 user not found

    Get Audit Log Export Configuration

    ▼
    GET /api/orgs/{orgName}/auditlogs/export/config

    GetAuditLogExportConfiguration returns the organization’s current audit log export configuration. If the organization has not configured its audit logs for export, returns a 404.

    Request Parameters

    • orgName string path required
      The organization name

    Responses

    200 OK
    Schema: OrganizationAuditLogExportSettings
    • enabled boolean required
      Whether audit log export is currently active. May be paused automatically if the configured destination repeatedly fails to authenticate.
    • s3Config AuditLogsExportS3Config required
      The S3 configuration for exporting audit logs.
    • ↳ s3BucketName string required
      Name of the S3 bucket to export audit logs to.
    • ↳ s3PathPrefix string optional
      Optional path prefix within the S3 bucket for exported log files.
    • ↳ iamRoleArn string required
      ARN of the IAM role that Pulumi will assume to write to the S3 bucket.
    • lastResult AuditLogExportResult required
      The result of the last audit log export attempt.
    • ↳ timestamp integer required
      The timestamp
    • ↳ message string required
      If the last result was successful, message will be “”. Any other value is a user-facing error message.
    Errors: 404 Audit log export configuration

    Update Audit Log Export Configuration

    ▼
    POST /api/orgs/{orgName}/auditlogs/export/config

    Creates or updates the organization’s automated audit log export configuration. Audit log export enables automatic delivery of audit events to an S3 bucket for long-term retention and SIEM integration. The configuration includes the S3 bucket details and IAM role for authentication. This feature is available on Business Critical edition.

    Request Parameters

    • orgName string path required
      The organization name

    Request Body

    Schema: UpdateOrganizationAuditLogExportSettingsRequest
    • newEnabled boolean required
      Whether the audit log export is enabled.
    • newS3Configuration AuditLogsExportS3Config required
      The new S3 configuration for audit log export.
    • ↳ s3BucketName string required
      Name of the S3 bucket to export audit logs to.
    • ↳ s3PathPrefix string optional
      Optional path prefix within the S3 bucket for exported log files.
    • ↳ iamRoleArn string required
      ARN of the IAM role that Pulumi will assume to write to the S3 bucket.

    Responses

    204 No Content
    Errors: 400 Audit log export is not available for this organization.

    Delete Audit Log Export Configuration

    ▼
    DELETE /api/orgs/{orgName}/auditlogs/export/config

    DeleteAuditLogExportConfiguration removes an organization’s audit log export settings. Skip feature validation so removal can happen if org no longer has access to feature.

    Request Parameters

    • orgName string path required
      The organization name

    Responses

    204 No Content
    Errors: 400 Organization has not configured audit log export.

    Force Audit Log Export

    ▼
    POST /api/orgs/{orgName}/auditlogs/export/config/force

    ForceAuditLogExport exports the audit logs for the organization for a user-supplied timestamp. This can be used to backfill data that may have been missed due to an outage or permissions issue.

    Request Parameters

    • orgName string path required
      The organization name
    • timestamp integer query optional
      Unix timestamp to export audit logs for (used for backfilling missed data)

    Responses

    200 OK
    Schema: AuditLogExportResult
    • timestamp integer required
      The timestamp
    • message string required
      If the last result was successful, message will be “”. Any other value is a user-facing error message.
    Errors: 400 Audit log export is not available for this organization. 404 Audit log export configuration

    Test Audit Log Export Configuration

    ▼
    POST /api/orgs/{orgName}/auditlogs/export/config/test

    TestAuditLogExportConfiguration uses the provided audit log configuration and checks if we are able to successfully write some data.

    Request Parameters

    • orgName string path required
      The organization name

    Request Body

    Schema: AuditLogsExportS3Config
    • s3BucketName string required
      Name of the S3 bucket to export audit logs to.
    • s3PathPrefix string optional
      Optional path prefix within the S3 bucket for exported log files.
    • iamRoleArn string required
      ARN of the IAM role that Pulumi will assume to write to the S3 bucket.

    Responses

    200 OK
    Schema: AuditLogExportResult
    • timestamp integer required
      The timestamp
    • message string required
      If the last result was successful, message will be “”. Any other value is a user-facing error message.
    Errors: 400 Audit log export is not available for this organization.

    Get Audit Logs Reader Kind

    ▼
    GET /api/orgs/{orgName}/auditlogs/reader-kind

    GetAuditLogsReaderKind returns whether the audit log is being read from MySQL or DynamoDB to control the event filtering UI on the front end.

    Request Parameters

    • orgName string path required
      The organization name

    Responses

    200 OK

    List Audit Log Events Handler V2

    ▼
    GET /api/orgs/{orgName}/auditlogs/v2

    Lists audit log events for an organization. Uses startTime as the lower bound and endTime as the upper bound of the query range. Supports filtering by event type and user.

    Request Parameters

    • orgName string path required
      The organization name
    • continuationToken string query optional
      Token for paginated result retrieval
    • endTime integer query optional
      Upper bound of the query range (unix timestamp)
    • eventFilter string query optional
      Filter audit logs by event type
    • format string query optional
      Response format: ‘json’ (default)
    • startTime integer query optional
      Lower bound of the query range (unix timestamp)
    • userFilter string query optional
      Filter audit logs by username

    Responses

    200 OK
    Schema: ResponseAuditLogs
    • continuationToken string optional
      A continuation token for paginating through audit log results.
    • auditLogEvents array[AuditLogEvent] required
      The list of audit log events.
    • ↳ timestamp integer required
      Unix epoch timestamp (seconds) when the event occurred.
    • ↳ sourceIP string required
      IP address of the client that triggered the event.
    • ↳ event string required
      The audit event type identifier (e.g. ‘stack.update’, ‘member.added’).
    • ↳ description string required
      Human-readable description of the event.
    • ↳ user UserInfo required
      The user who performed the action.
    • ↳ tokenID string optional
      ID of the access token used to authenticate, if applicable.
    • ↳ tokenName string optional
      Name of the access token used to authenticate, if applicable.
    • ↳ reqOrgAdmin boolean optional
      Whether the action that triggered this event required the organization ADMIN role.
    • ↳ reqStackAdmin boolean optional
      Whether the action required stack admin privileges.
    • ↳ authFailure boolean optional
      Whether this event represents a failed authentication attempt.
    • ↳ actorName string optional
      Display name of the non-human actor (e.g. deploy token name) that triggered the event.
    • ↳ actorUrn string optional
      Pulumi URN of the non-human actor that triggered the event.
    Errors: 400 invalid query params 404 user not found

    Export Audit Log Events Handler V2

    ▼
    GET /api/orgs/{orgName}/auditlogs/v2/export

    Exports audit log events in a downloadable format (CSV or CEF). Supports filtering by time range using startTime (lower bound) and endTime (upper bound), as well as filtering by event type and user.

    Request Parameters

    • orgName string path required
      The organization name
    • continuationToken string query optional
      Token for paginated result retrieval
    • endTime integer query optional
      Upper bound of the query range (unix timestamp)
    • eventFilter string query optional
      Filter audit logs by event type
    • format string query optional
      Response format: ‘cef’ or ‘csv’ (defaults to csv)
    • startTime integer query optional
      Lower bound of the query range (unix timestamp)
    • userFilter string query optional
      Filter audit logs by username

    Responses

    200 OK
    Errors: 400 Audit Logs is available only to organizations with an Enterprise subscription. 404 user not found