> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.synthesia.io/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.synthesia.io/docs/_mcp/server. # Audit Logs > **Info** > > ### Audit Logs are available on Enterprise plans. > > All endpoints require API key authentication. > **Note** > > ### Note: > > Only Organization Admins can access Audit Logs (via [Organization Settings](https://docs.synthesia.io/docs/organization-settings) or [Synthesia API](/docs/video-api-reference/audit-logs/get-audit-log-events)). The Audit Logs API returns a record of actions taken across your organization and workspaces: who did what, when, and to what. Use it for compliance reporting, security monitoring, and activity tracking. To browse and filter audit logs in the Synthesia app instead of calling the API, see [Audit logs](https://docs.synthesia.io/docs/audit-logs). ## Endpoints | Method | Endpoint | Purpose | | ------ | ----------------------------- | --------------------------------------------- | | `GET` | `/v2/auditLogs/events` | Query audit log events with simple filters. | | `POST` | `/v2/auditLogs/events/search` | Advanced search with complex filter criteria. | | `POST` | `/v2/auditLogs/export` | Export audit logs as a CSV file. | ### Query audit log events ``` GET https://api.synthesia.io/v2/auditLogs/events ``` Simple query endpoint for retrieving paginated audit events. **Key behavior:** * Exactly one of `workspaceId` or `organizationId` must be provided. * Multiple values for `actions` and `actorIds` are comma-separated. * Dates are Unix timestamps (seconds since epoch). **Query parameters:** | Parameter | Type | Required | Description | | ---------------- | ------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspaceId` | string (UUID) | Conditional | Filter by workspace. Mutually exclusive with `organizationId`. | | `organizationId` | string (UUID) | Conditional | Filter by organization. Mutually exclusive with `workspaceId`. | | `actions` | string | No | Comma-separated action names, for example `workspace.user.invited,workspace.invitation.accepted`. See [Event types](#event-types) for the full list. | | `actorIds` | string | No | Comma-separated actor IDs. | | `targetId` | string | No | Filter by a specific target resource. | | `startDate` | integer | No | Unix timestamp (seconds). Filters events from this date onwards. Must be before `endDate` if both are provided. | | `endDate` | integer | No | Unix timestamp (seconds). Filters events before this date. Must be after `startDate` if both are provided. | | `cursor` | string | No | Pagination cursor from a previous response. | | `limit` | integer | No | Results per page, 1 to 200. Default: 50. | **Response:** ```json { "events": [ { "id": "7d8307d2-63f3-4e86-85db-8feae494f7e2", "action": "workspace.license.consumed", "status": "success", "actor": { "type": "user", "id": "9a0840a7-a4be-42f7-9d2c-a6d96ccc6ba6", "name": "Jamie Rivera", "email": "jamie.rivera@example.com" }, "target": { "type": "user", "id": "91f0be7b-055a-4766-8457-79dbeb1c351d", "name": "Alex Chen" }, "context": { "workspaceId": "99ba788e-eaeb-4b0c-ae4e-901575d6f28c", "organizationId": "73a6bbf3-eed0-4d31-8dd9-16435fe2ee38", "ipAddress": null }, "details": { "previousLicenseType": "free", "newLicenseType": "full", "targetUserEmail": "alex.chen@example.com", "targetUserId": "91f0be7b-055a-4766-8457-79dbeb1c351d", "source": "admin_action", "workspaceName": "Sales Workspace", "organizationName": "Example Org" }, "metadata": { "createdAt": "2026-01-11T16:47:57.658000Z", "processedAt": "2026-01-11T16:47:58.324000Z" } } ], "nextCursor": "51332afa-4419-405f-9a85-fe437ce683aa", "hasMore": true } ``` ### Search audit log events ``` POST https://api.synthesia.io/v2/auditLogs/events/search ``` Advanced search for complex filtering scenarios. Use this endpoint instead of `GET /v2/auditLogs/events` when: * Filtering by 50 or more actions or actors. * You need programmatic access with a JSON request body. * Your filter combination is too complex for query parameters. **Request body:** ```json { "organizationId": "73a6bbf3-eed0-4d31-8dd9-16435fe2ee38", "startDate": 1736524800, "endDate": 1736697600, "actions": ["billing.credits.consumed", "dubbing.project.created"], "actorIds": ["9a0840a7-a4be-42f7-9d2c-a6d96ccc6ba6", "91f0be7b-055a-4766-8457-79dbeb1c351d"], "cursor": null, "limit": 100 } ``` **Response:** ```json { "events": [ { "id": "59fa0207-13d9-45fe-a54c-1799658ccc31", "action": "billing.credits.consumed", "status": "success", "actor": { "type": "system", "id": "billing_system", "name": "Billing System", "email": null }, "target": { "type": "workspace", "id": "1f32e8d4-1594-43e2-8caa-1e0a48e00bcc", "name": "Enterprise Workspace" }, "context": { "workspaceId": "1f32e8d4-1594-43e2-8caa-1e0a48e00bcc", "organizationId": "73a6bbf3-eed0-4d31-8dd9-16435fe2ee38", "ipAddress": "internal" }, "details": { "feature": "DUBBING_DURATION", "amount": 5.845, "operationType": "credit" }, "metadata": { "createdAt": "2026-01-11T16:49:00.051000Z", "processedAt": "2026-01-11T16:49:00.387000Z" } } ], "nextCursor": "b8d4c4ed-1682-4831-af22-3723f400119d", "hasMore": true } ``` ### Export audit logs as CSV ``` POST https://api.synthesia.io/v2/auditLogs/export ``` Exports filtered audit logs as a downloadable CSV file. See [CSV structure](#csv-structure) for the columns it contains. **Key behavior:** * Maximum of 10,000 events per export. If your filter matches more, the response is truncated and the filename includes a `_TRUNCATED` suffix. * The response is binary CSV data (`Content-Type: application/csv`). **Request body:** ```json { "organizationId": "73a6bbf3-eed0-4d31-8dd9-16435fe2ee38", "startDate": 1733932192, "endDate": 1736524192, "actions": ["billing.credits.consumed"], "actorIds": null, "targetId": null } ``` **Response:** binary CSV file, with a `Content-Disposition` header containing the filename, for example `audit_logs_export_20260111_165018.csv`. Exporting is itself an audited action. It generates its own event: ```json { "id": "2543a303-74f9-46a1-aba6-9c0538f92a3e", "action": "audit_logs.exported", "status": "success", "actor": { "type": "user", "id": "91f0be7b-055a-4766-8457-79dbeb1c351d", "name": "Jamie Rivera", "email": "jamie.rivera@example.com" }, "target": { "type": "organization", "id": "73a6bbf3-eed0-4d31-8dd9-16435fe2ee38", "name": null }, "context": { "workspaceId": null, "organizationId": "73a6bbf3-eed0-4d31-8dd9-16435fe2ee38", "ipAddress": null }, "details": { "eventCount": 62, "truncated": false, "filename": "audit_logs_export_20260111_165018.csv", "filters": { "start_date": "2025-12-12T16:49:52+00:00", "end_date": "2026-01-11T16:49:52+00:00", "actor_ids": ["9a0840a7-a4be-42f7-9d2c-a6d96ccc6ba6", "91f0be7b-055a-4766-8457-79dbeb1c351d"] } }, "metadata": { "createdAt": "2026-01-11T16:50:18.980000Z", "processedAt": "2026-01-11T16:50:18.983000Z" } } ``` ## Pagination The Audit Logs API uses cursor-based pagination, which stays stable even when new events are added between requests. 1. Make an initial request without a `cursor` parameter. 2. The response includes `nextCursor` and `hasMore`. 3. Pass `nextCursor` as the `cursor` parameter in your next request. 4. Repeat until `hasMore` is `false`. | Field | Type | Description | | ------------ | -------------- | ---------------------------------------------------------------------------------------------- | | `nextCursor` | string \| null | Pass this as the `cursor` parameter in your next request. `null` if there are no more results. | | `hasMore` | boolean | Whether more events exist beyond the current page. `false` means `nextCursor` is also `null`. | **Best practices:** * Check `hasMore` to decide whether to keep paginating, rather than only checking whether `nextCursor` is `null`. * Keep filter parameters (`startDate`, `endDate`, `actions`, and so on) identical across all requests in a paginated sequence. Changing filters mid-sequence means starting over without a cursor. * If `events` is empty but `hasMore` is `true`, keep paginating. There may be matching results further on. * Treat cursors as opaque tokens. Don't parse or modify them. * Events are sorted by `createdAt` descending, then by `id` descending, for consistent ordering across pages. * There's no offset or page-number based pagination, only cursor-based. ## Response codes | Code | Description | | ---- | --------------------------------------------------------------------------------- | | 200 | Success. | | 400 | Invalid parameters, for example both `workspaceId` and `organizationId` provided. | | 403 | Forbidden. Invalid API key, or Public API access disabled. | | 404 | Workspace or organization not found. | | 429 | Rate limit exceeded. | | 5XX | Server error. | ## Data model reference ### Actor types | Type | Description | | --------- | --------------------------------------------------------------------------------------- | | `user` | A human user performed the action. | | `system` | Synthesia's systems performed the action automatically, for example the billing system. | | `service` | An external service or integration performed the action. | ### Target types | Type | Description | | -------------- | --------------------------- | | `workspace` | A workspace. | | `video` | A video or dubbing project. | | `user` | A user account. | | `organization` | An organization. | | `asset` | A media asset. | ## CSV structure Exported files are named `audit_logs_export__.csv`. A single export is capped at 10,000 events—if your filtered result has more, the file is truncated and `_TRUNCATED` is appended to the filename. Narrow your date range or filters to get the rest. Each row has these columns: | Column | Description | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `event_id` | Unique identifier for the event. | | `timestamp` | When the event occurred, in ISO 8601 (UTC). | | `action` | The event, in `domain.resource.past_tense_verb` format (for example, `workspace.user.invited`). | | `actor_type` | Who or what performed the action: `user` or `system`. | | `actor_id` | The actor's unique identifier. | | `actor_name` | The actor's display name. | | `actor_email` | The actor's email address. | | `target_type` | The kind of thing the action was performed on (for example, `workspace`, `user`, `video`, `asset`). | | `target_id` | The target's unique identifier. | | `target_name` | The target's display name. | | `status` | Whether the action succeeded, for example `success`. | | `details` | A JSON-encoded string with information specific to that action, such as what changed from and to. Quotes inside it are escaped and need unescaping before you parse it. | | `workspace_id` | The workspace the action occurred in, if applicable. | | `organization_id` | The organization the action occurred in. | | `ip_address` | The IP address the action came from. Blank for most user actions, and `internal` for actions performed by Synthesia's systems. | > **Note** > > ### Note: > > The CSV flattens the `actor`, `target`, and `context` objects from the JSON response into individual columns, and uses a single `timestamp` rather than the JSON response's separate `createdAt` and `processedAt`. ## Event structure Each event, whether from `events`, `events/search`, or a CSV row, records: * `id`: a unique identifier for the event. * `action`: what was done, in `domain.resource.past_tense_verb` format (for example, `workspace.user.invited`). * `status`: whether the action succeeded. * `actor`: who or what performed the action. * `target`: what the action was performed on. * `context`: the workspace, organization, and IP address the action occurred in. * `details`: additional information specific to that action, such as what changed from and to. * `metadata`: timestamps for when the event was created and processed. ## Event types Actions follow the `domain.resource.past_tense_verb` format shown throughout this reference. Each event's **Name** is the label it appears under in the Synthesia app's Events filter—see [Audit logs](https://docs.synthesia.io/docs/audit-logs) for how to browse events there. A dash (—) means the event isn't available in the list of filter options. ### Authentication | Event | Name | Description | | ---------------------------- | -------------------------- | ------------------ | | `user.authentication.login` | User Authentication Login | A user logged in. | | `user.authentication.logout` | User Authentication Logout | A user logged out. | ### User | Event | Name | Description | | ------------------------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `user.profile.updated` | User Profile Updated | A profile field was updated. | | `user.profile_picture.updated` | User Profile Picture Updated | A profile picture was uploaded or deleted. | | `user.email.changed` | — | A user's email address was changed. Can be triggered by the user themselves, or automatically, for example by an SSO sync. | | `user.account.banned` | — | A user account was banned. | | `user.api_key.created` | User Api Key Created | An API key was created. | | `user.scim.created` | User SCIM Created | A user was created via SCIM provisioning. | | `user.scim.updated` | User SCIM Updated | A user was updated via SCIM provisioning. | | `user.scim.deleted` | User SCIM Deleted | A user was deleted via SCIM provisioning. | | `user.jit.provisioned` | User JIT Provisioned | A user was provisioned via Just-in-Time (JIT) provisioning. | ### Workspace | Event | Name | Description | | ------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `workspace.created` | Workspace Created | A workspace was created. | | `workspace.bound` | Workspace Bound | A workspace was bound to an organization. Performed by Synthesia's systems, not a person. | | `workspace.unbound` | Workspace Unbound | A workspace was unbound from an organization. Performed by Synthesia's systems, not a person. | | `workspace.deletion.scheduled` | Workspace Deletion Scheduled | Workspace deletion was scheduled. | | `workspace.name.changed` | Workspace Name Changed | The workspace name was changed. | | `workspace.icon.changed` | Workspace Icon Changed | The workspace icon was uploaded or deleted. | | `workspace.insights.requested` | Workspace Insights Requested | An Insights report was requested. | | `workspace.preferences.updated` | Workspace Preferences Updated | A workspace setting was changed. | | `workspace.joining_strategy.updated` | Workspace Joining Strategy Updated | The workspace's discoverability setting was changed (for example, between invitation-only and open for anyone from listed domains). | | `workspace.invite_link.updated` | Workspace Invite Link Updated | The workspace's invite link was turned on or off. | | `workspace.invite_link.reset` | Workspace Invite Link Reset | The workspace's invite link was reset, invalidating the old one. | | `workspace.share_page_colors.updated` | Workspace Share Page Colors Updated | The share page's primary, secondary, or background color was changed. | | `workspace.share_page_logo.updated` | Workspace Share Page Logo Updated | The share page logo was uploaded or deleted. | | `workspace.user.invited` | Workspace User Invited | A user was invited to the workspace. | | `workspace.invitation.accepted` | Workspace Invitation Accepted | A workspace invitation was accepted. | | `workspace.invitation.revoked` | Workspace Invitation Revoked | A workspace invitation was revoked. | | `workspace.user.role_changed` | Workspace User Role Changed | A user's role in the workspace was changed. | | `workspace.user.removed` | Workspace User Removed | A user was removed from the workspace. | | `workspace.user.left` | Workspace User Left | A user left the workspace voluntarily. | | `workspace.license.changed` | Workspace License Changed | A user's license in the workspace was changed. | | `workspace.license.consumed` | Workspace License Consumed | A user's license in the workspace was upgraded to Full. | | `workspace.license.released` | Workspace License Released | A user's license in the workspace was downgraded to Restricted. | ### Organization | Event | Name | Description | | ------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------ | | `organization.created` | — | An organization was created. | | `organization.name.changed` | Organization Name Changed | The organization name was changed. | | `organization.preferences.updated` | Organization Preferences Updated | An organization setting was changed. | | `organization.workspace_discoverability_domain.added` | Organization Workspace Discoverability Domain Added | An allowed domain was added for workspace discoverability. | | `organization.workspace_discoverability_domain.removed` | Organization Workspace Discoverability Domain Removed | An allowed domain was removed from workspace discoverability. | | `organization.sso_settings.updated` | Organization SSO Settings Updated | Organization SSO settings were updated. | | `organization.invitation.resent` | Organization Invitation Resent | An organization invitation was resent. | | `organization.invitation.revoked` | Organization Invitation Revoked | An organization invitation was revoked. | | `organization.user.role_changed` | Organization User Role Changed | A user's role in the organization was changed. | | `organization.user.removed` | Organization User Removed | A user was removed from the organization. | | `organization.license.changed` | Organization License Changed | A user's license in the organization was changed. | | `organization.license.consumed` | Organization License Consumed | A user's license in the organization was upgraded to Full. | | `organization.license.released` | Organization License Released | A user's license in the organization was downgraded to Restricted. | | `organization.insights.requested` | Organization Insights Requested | An Insights report was requested. | ### Billing | Event | Name | Description | | -------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `billing.credits.consumed` | Billing Credits Consumed | Credits were consumed by a feature. | | `billing.credits.allocated` | Billing Credits Allocated | Credits were allocated to a workspace. | | `billing.credits.added` | Billing Credits Added | Credits were manually granted to an account, for example by Synthesia support. | | `billing.credits.purchased` | Billing Credits Purchased | Credits were purchased. | | `billing.credit_allocation_strategy.changed` | Billing Credit Allocation Strategy Changed | The organization's credit allocation strategy was changed, between a shared pool across all workspaces and per-workspace allocation. | | `billing.workspace_allocation.updated` | Billing Credits Allocation Updated | A workspace's specific credit allocation amount was changed. | ### Email send cap | Event | Name | Description | | -------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------ | | `email_send_cap.recipient_exclusion.granted` | Email Send Cap Recipient Exclusion Granted | A recipient was excluded from the email send cap. | | `email_send_cap.recipient_exclusion.revoked` | Email Send Cap Recipient Exclusion Revoked | A recipient's exclusion from the email send cap was revoked. | ### Content | Event | Name | Description | | --------------------------- | ------------------------- | ------------------------------- | | `dubbing.project.created` | Dubbing Project Created | A dubbing project was created. | | `asset.powerpoint.uploaded` | Asset Powerpoint Uploaded | A PowerPoint file was imported. | | `scorm.package.downloaded` | — | A SCORM package was downloaded. | ### Integrations Covers HRIS and messaging integrations for the Learner Portal, and other external tool connections. | Event | Name | Description | | ----------------------------------- | ---- | -------------------------------------------------------- | | `integrations.connection.initiated` | — | A connection to an external tool was started. | | `integrations.connection.created` | — | A connection to an external tool completed successfully. | | `integrations.connection.deleted` | — | A connection to an external tool was disconnected. | ### Audit logs | Event | Name | Description | | --------------------- | ------------------- | ---------------------------------- | | `audit_logs.exported` | Audit Logs Exported | An audit log export was requested. | ### Learner Portal The [Learner Portal](https://docs.synthesia.io/docs/learner-app) has its own set of events, covering Learner Groups, content assignment, and role entitlements. These are distinct from the core Admin/Member/Guest model—the Learner Portal has its own roles (Enablement Admin, Organization Admin, Manager, and Learner). | Event | Name | Description | | ---------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `entitlement.granted` | — | A Learner Portal role (for example, Enablement Admin) was granted to a user. | | `entitlement.revoked` | — | A Learner Portal role was revoked from a user. | | `lms.hris_sync_config.created` | LMS Hris Sync Config Created | An HRIS sync was connected. | | `lms.hris_sync_config.updated` | LMS Hris Sync Config Updated | An HRIS sync's configuration was changed. | | `lms.hris_sync_config.deleted` | LMS Hris Sync Config Deleted | An HRIS sync was disconnected. | | `lms.learner_group.created` | LMS Learner Group Created | A Learner Group was created. Groups are either **manual** (fixed membership) or **dynamic** (populated automatically based on rules, for example department or email domain). | | `lms.learner_group.updated` | LMS Learner Group Updated | A Learner Group's name or targeting rule was changed. | | `lms.learner_group.deleted` | LMS Learner Group Deleted | A Learner Group was deleted. | | `lms.learner_group_member.added` | LMS Learner Group Member Added | A learner was added to a Learner Group. | | `lms.learner_group_member.removed` | LMS Learner Group Member Removed | A learner was removed from a Learner Group. | | `lms.assignment_target.added` | — | A learner was assigned a Roleplay Session. | | `lms.assignment_target.removed` | — | A learner's assignment to a Roleplay Session was removed. |