# List Audit Logs

`GET /api/v1/audit-logs`

## Description
Retrieve audit logs for your organization with cursor-based pagination. Requires an Enterprise subscription and organization admin or owner role. Only an unscoped personal API key can call this endpoint. Workspace keys, organization keys, and keys with scope grants receive 403.

## Parameters

- **action** (query) — `string`: Filter by action type (e.g., workflow.created, workflow.deployed, member.invited).

- **resourceType** (query) — `string`: Filter by resource type (e.g., workflow, workspace, member).

- **resourceId** (query) — `string`: Filter by a specific resource ID.

- **workspaceId** (query) — `string`: Filter by workspace.

- **organizationId** (query) — `string`: Organization to query. Organization keys are bound to their own organization. A different value returns 403.

- **actorId** (query) — `string`: Filter by the user who performed the action. Must be a member of your organization.

- **workloadIdentityId** (query) — `string`: Filter by a registered workload identity within the selected organization. Machine events are included independently of current human membership.

- **startDate** (query) — `string`: Only return logs after this ISO 8601 timestamp (inclusive).

- **endDate** (query) — `string`: Only return logs before this ISO 8601 timestamp (inclusive).

- **includeDeparted** (query) — `boolean`: When true, includes audit logs from users who have left the organization.

- **limit** (query) — `integer`: Maximum number of audit log entries to return per page. Must be between 1 and 100.

- **cursor** (query) — `string`: Pagination cursor returned from a previous request's nextCursor field.

## Responses

### 200 — A paginated list of audit log entries.

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "description": "Array of audit log entries for the current page.",
      "items": {
        "type": "object",
        "description": "An enterprise audit log entry recording an action taken in the workspace.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the audit log entry.",
            "example": "audit_2c3d4e5f6g"
          },
          "workspaceId": {
            "type": "string",
            "nullable": true,
            "description": "The workspace where the action occurred.",
            "example": "ws_xyz789"
          },
          "actorId": {
            "type": "string",
            "nullable": true,
            "description": "The user ID of the person who performed the action.",
            "example": "user_abc123"
          },
          "actorName": {
            "type": "string",
            "nullable": true,
            "description": "Display name of the actor. Workload events retain the registered identity's admitted name snapshot.",
            "example": "Jane Smith"
          },
          "actorKind": {
            "type": "string",
            "description": "Actor category, such as user or workload.",
            "example": "workload"
          },
          "workloadIdentityId": {
            "type": "string",
            "nullable": true,
            "description": "Registered workload identity ID for machine events; null for human events or a removed binding. Resource ownership is separate from this actor.",
            "example": "workload_abc123"
          },
          "actorEmail": {
            "type": "string",
            "nullable": true,
            "description": "Email address of the person who performed the action.",
            "example": "jane@example.com"
          },
          "action": {
            "type": "string",
            "description": "The action that was performed (e.g., workflow.created, member.invited).",
            "example": "workflow.deployed"
          },
          "resourceType": {
            "type": "string",
            "description": "The type of resource affected (e.g., workflow, workspace, member).",
            "example": "workflow"
          },
          "resourceId": {
            "type": "string",
            "nullable": true,
            "description": "The unique identifier of the affected resource.",
            "example": "wf_1a2b3c4d5e"
          },
          "resourceName": {
            "type": "string",
            "nullable": true,
            "description": "Display name of the affected resource.",
            "example": "Customer Support Agent"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Human-readable description of the action.",
            "example": "Deployed workflow Customer Support Agent"
          },
          "metadata": {
            "type": "object",
            "nullable": true,
            "description": "Additional context about the action.",
            "example": null
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp when the action occurred.",
            "example": "2025-06-20T14:15:22Z"
          }
        }
      }
    },
    "nextCursor": {
      "type": "string",
      "nullable": true,
      "description": "Cursor for fetching the next page. null when there are no more results."
    },
    "limits": {
      "type": "object",
      "description": "Rate limit and usage information attached to the /api/v1 workflows, logs, and audit logs responses. The Execute Workflow and Get Job Status responses do not include it.",
      "properties": {
        "workflowExecutionRateLimit": {
          "type": "object",
          "description": "Current rate limit status for workflow executions.",
          "properties": {
            "sync": {
              "description": "Rate limit bucket for synchronous executions.",
              "$ref": "#/components/schemas/RateLimitBucket"
            },
            "async": {
              "description": "Rate limit bucket for asynchronous executions.",
              "$ref": "#/components/schemas/RateLimitBucket"
            }
          }
        },
        "usage": {
          "type": "object",
          "description": "Current billing period usage and plan limits.",
          "properties": {
            "currentPeriodCost": {
              "type": "number",
              "description": "Total spend in the current billing period in USD.",
              "example": 1.25
            },
            "limit": {
              "type": "number",
              "description": "Maximum allowed spend for the current billing period in USD.",
              "example": 50
            },
            "plan": {
              "type": "string",
              "description": "Your current subscription plan (e.g., free, pro, team).",
              "example": "pro"
            },
            "isExceeded": {
              "type": "boolean",
              "description": "Whether the usage limit has been exceeded. Executions may be blocked when true.",
              "example": false
            }
          }
        }
      }
    }
  }
}
```

### 400 — Invalid request parameters. Check the details array for specific validation errors.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Human-readable error message describing the validation failure."
    },
    "details": {
      "type": "array",
      "description": "List of specific validation errors with field-level details.",
      "items": {
        "type": "object"
      }
    }
  }
}
```

### 401 — Invalid or missing API key. Ensure the X-API-Key header is set with a valid key.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Human-readable error message."
    }
  }
}
```

### 403 — Access denied. You do not have permission to access this resource. For audit log endpoints, this requires an Enterprise subscription and organization admin/owner role.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Human-readable error message."
    }
  }
}
```

### 429 — Rate limit exceeded. Wait for the duration specified in the Retry-After header before retrying.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Human-readable error message with rate limit details."
    }
  }
}
```
