Access Audit Logs via API
All teams have an Audit log accessible from the Admin Team Center, or via API.
Our Audit logs API was built for teams who have additional security, legal, or compliance requirements. With the API, you can:
- Send data to a security information and event management (SIEM) tool.
- Watch for potential security issues or malicious attempts to access your team.
- Use the API to build custom apps for better insight into how your company uses PagerDuty Workflow Automation.
note
- Note: Audit logs show data dating back to mid-September 2021, when this feature and API method became available to teams.
How to use the Audit Logs API
To use the API, you’ll need to use the audit log endpoint and authenticate with an access token.
GET https://[$team].pushbot.com/v1/[$team]/audit-logs
By default, the API returns a content-type of application/json
and uses pagination. You can also return the response as text/csv
. The API supports filtering, excluding and sorting.
Authenticating with the API
Once you generate a token, use it as the content of an Authorization header, for example:
Authorization: Bearer d47ce248488acd8e8da8c98938ad8e9c81091838acea028d0e8f0b0a083717a
Any team admin can view and use the Audit logs API and access token. You can also regenerate the token at any time.
- Navigate to the Audit logs section of the Admin Team Center. > Admin > Audit Logs
-
Select the API Access option in the page menu.
- Use to generate an access token. This token will only allow access into PagerDuty Workflow Automation audit log data for this team, and does not allow access into any other PagerDuty Workflow Automation APIs or data.
Using query parameters to filter, exclude, and sort
You can attach query parameters to the request to filter the data. To use query parameters, append the parameter onto your audit log endpoint. For example, to filter audit log events by a userID, you could use:
GET https://[$team].pushbot.com/v1/[$team]/audit-logs?userID=1091838acea028d0e8f0b0a08
As another example, to filter by action type, just append ?action=
followed by the parameter value below to the audit log endpoint:
GET https://[$team].pushbot.com/v1/[$team]/audit-logs?action=Action%20status%20changed
Or for multiple filters:
GET https://[$team].pushbot.com/v1/[$team]/audit-logs?action=Action%20status%20changed&action=Group%20activated
There are 7 types of filters you can use. The filters can be combined together, except in specific cases like userID and excludedUserID. Each filter has example configurations you can use as templates for your own API work.
startTime
The minimum date to filter events by, expressed in Unix time.
Example | Description |
---|---|
https://[$team].pushbot.com/v1/[$team]/audit-logs?startTime=1630997503 |
Return all events after September 6th |
https://[$team].pushbot.com/v1/[$team]/audit-logs?startTime=1630997503&endTime=1631083982 |
Return all events after September 6th, and before September 8th |
https://[$team].pushbot.com/v1/[$team]/audit-logs?startTime=1630997503&action=Table%20created |
Return all events after September 8th, with the action type “Table created” |
There are many ways to get a time in Unix time, like using .valueOf()
method in javascript. You can also use tools online to find a Unix time like https://www.unixtimestamp.com/.
endTime
The maximum date to filter events by, expressed in Unix time.
Example | Description |
---|---|
https://[$team].pushbot.com/v1/[$team]/audit-logs?endTime=1631083982 |
Return all events before September 8th |
https://[$team].pushbot.com/v1/[$team]/audit-logs?startTime=1630997503&endTime=1631083982 |
Return all events after September 6th, and before September 8th |
https://[$team].pushbot.com/v1/[$team]/audit-logs?endTime=1631083982&action=Group%20deactivated |
Return all events before September 8th, with the action type “Group deactivated” |
There are many ways to get a time in Unix time, like using .valueOf()
method in javascript. You can also use tools online to find a Unix time like https://www.unixtimestamp.com/.
userID
The userID or userIDs to filter audit log events by. Use this parameter to filter for a userID. This cannot be used in conjunction with the excludedUserID parameter.
To find a user’s ID, use the users application table in the user ID
column, or from the user’s profile page by checking the page URL.
Example | Description |
---|---|
https://[$team].pushbot.com/v1/[$team]/audit-logs?userID=1091838acea028d0e8f0b0a08 |
Return all events with the userID |
https://[$team].pushbot.com/v1/[$team]/audit-logs?userID=1091838acea028d0e8f0b0a08&userID=24552c0528505e55f5b5a08&userID=33bac4b5a5cba5c4b4c5a4d |
Return all events with any of the 3 user ID’s |
https://[$team].pushbot.com/v1/[$team]/audit-logs?startTime=1630997503&userID=24552c0528505e55f5b5a08 |
Return all events after September 6th with the following userID |
excludedUserID
The userID or userIDs to exclude from the results. Use this parameter to filter for everything but the userID. This cannot be used in conjunction with the userID parameter.
To find a user’s ID, use the users application table in the user ID
column, or from the user’s profile page by checking the page URL.
Example | Description |
---|---|
https://[$team].pushbot.com/v1/[$team]/audit-logs?excludedUserID=1091838acea028d0e8f0b0a08 |
Return all events without the following userID |
https://[$team].pushbot.com/v1/[$team]/audit-logs?excludedUserID=1091838acea028d0e8f0b0a08&excludedUserID=24552c0528505e55f5b5a08&excludedUserID=33bac4b5a5cba5c4b4c5a4d |
Return all events without any of the 3 user ID’s |
https://[$team].pushbot.com/v1/[$team]/audit-logs?startTime=1630997503&excludedUserId=24552c0528505e55f5b5a08 |
Return all events after September 6th without the following userID |
action
The action or actions to filter audit log events by. Use this parameter to filter for an action. This cannot be used in conjunction with the excludedAction parameter.
Example | Description |
---|---|
https://[$team].pushbot.com/v1/[$team]/audit-logs?action=Group%20deactivated |
Return all events associated with a specific action type |
https://[$team].pushbot.com/v1/[$team]/audit-logs?action=Group%20deactivated&action=Table%20created |
Return all events associated with either of two action types |
https://[$team].pushbot.com/v1/[$team]/audit-logs?action=Group%20deactivated&userID=1091838acea028d0e8f0b0a08 |
Return all events associated with a specific userID and action type |
For a list of all the action and parameter values, see the following list of Audit log actions and descriptions.
Audit log actions and descriptions
To filter by an action, first find it in the left hand column. Then, take the formatted parameter value in the right column to use in your query.
Action | Parameter Value |
---|---|
Action status changed | Action%20status%20changed |
File uploaded | File%20uploaded |
Group created | Group%20created |
Group activated | Group%20activated |
Group deactivated | Group%20deactivated |
Group role changed | Group%20role%20changed |
User added to group | User%20added%20to%20group |
User removed from group | User%20removed%20from%20group |
Integration connection created | Integration%20connection%20created |
Integration connection removed | Integration%20connection%20removed |
Integration permissions changed | Integration%20permissions%20changed |
Table archived | Table%20archived |
Table column added | Table%20column%20added |
Table column removed | Table%20column%20removed |
Table created | Table%20created |
Table edited | Table%20edited |
Table permissions changed | Table%20permissions%20changed |
Table unarchived | Table%20unarchived |
Web form task completed | Web%20form%20task%20completed |
Task completed | Task%20completed |
Task reassigned | Task%20reassigned |
Team setting changed | Team%20setting%20changed |
Team SSO disabled | Team%20SSO%20disabled |
Team SSO enabled | Team%20SSO%20enabled |
User accepted invite | User%20accepted%20invite |
User activated | User%20activated |
User changed password | User%20changed%20password |
User deactivated | User%20deactivated |
User entered incorrect password | User%20entered%20incorrect%20password |
User attempted login when locked out | User%20attempted%20login%20when%20locked%20out |
User locked out | User%20locked%20out |
User logged in | User%20logged%20in |
User logged out | User%20logged%20out |
User profile changed | User%20profile%20changed |
User role changed | User%20role%20changed |
User sent invite | User%20sent%20invite |
Workflow archived | Workflow%20archived |
Workflow cancelled | Workflow%20cancelled |
Workflow commented on | Workflow%20commented%20on |
Workflow created | Workflow%20created |
Workflow draft created | Workflow%20draft%20created |
Workflow draft publish request cancellation | Workflow%20draft%20publish%20request%20cancellation |
Workflow draft publish request | Workflow%20draft%20publish%20request |
Workflow edited | Workflow%20edited |
Workflow exported | Workflow%20exported |
Workflow imported | Workflow%20imported |
Workflow instance edited | Workflow%20instance%20edited |
Workflow instance permissions changed | Workflow%20instance%20permissions%20changed |
Workflow permissions changed | Workflow%20permissions%20changed |
Workflow started | Workflow%20started |
Workflow trigger created | Workflow%20trigger%20created |
Workflow trigger edited | Workflow%20trigger%20edited |
Workflow trigger removed | Workflow%20trigger%20removed |
Workflow unarchived | Workflow%20unarchived |
Workspace created | Workspace%20created |
Workspace removed | Workspace%20removed |
Workflow added to workspace | Workflow%20added%20to%20workspace |
Workflow removed from workspace | Workflow%20removed%20from%20workspace |
Workspace added to another workspace | Workspace%20added%20to%20another%20workspace |
Workspace removed from another workspace | Workspace%20removed%20from%20another%20workspace |
excludedAction
The action or actions to exclude from the results. Use this parameter to filter for every action but the action specified. This cannot be used in conjunction with the action parameter.
Example | Description |
---|---|
https://[$team].pushbot.com/v1/[$team]/audit-logs?excludedAction=Group%20deactivated |
Return all events except those with a specific action type. |
https://[$team].pushbot.com/v1/[$team]/audit-logs?excludedAction=Group%20deactivated&excludedAction=Table%20created |
Return all events except those associated with either of two action types. |
https://[$team].pushbot.com/v1/[$team]/audit-logs?excludedAction=Group%20deactivated&userID=1091838acea028d0e8f0b0a08 |
Return all events associated with a specific userID, that aren’t associated with a specific action type |
For a list of all the action and parameter values, see the following list of Audit log actions and descriptions.
Audit log actions and descriptions
To filter by an action, first find it in the left hand column. Then, take the formatted parameter value in the right column to use in your query.
Action | Parameter Value |
---|---|
Action status changed | Action%20status%20changed |
File uploaded | File%20uploaded |
Group created | Group%20created |
Group activated | Group%20activated |
Group deactivated | Group%20deactivated |
Group role changed | Group%20role%20changed |
User added to group | User%20added%20to%20group |
User removed from group | User%20removed%20from%20group |
Integration connection created | Integration%20connection%20created |
Integration connection removed | Integration%20connection%20removed |
Integration permissions changed | Integration%20permissions%20changed |
Table archived | Table%20archived |
Table column added | Table%20column%20added |
Table column removed | Table%20column%20removed |
Table created | Table%20created |
Table edited | Table%20edited |
Table permissions changed | Table%20permissions%20changed |
Table unarchived | Table%20unarchived |
Web form task completed | Web%20form%20task%20completed |
Task completed | Task%20completed |
Task reassigned | Task%20reassigned |
Team setting changed | Team%20setting%20changed |
Team SSO disabled | Team%20SSO%20disabled |
Team SSO enabled | Team%20SSO%20enabled |
User accepted invite | User%20accepted%20invite |
User activated | User%20activated |
User changed password | User%20changed%20password |
User deactivated | User%20deactivated |
User entered incorrect password | User%20entered%20incorrect%20password |
User attempted login when locked out | User%20attempted%20login%20when%20locked%20out |
User locked out | User%20locked%20out |
User logged in | User%20logged%20in |
User logged out | User%20logged%20out |
User profile changed | User%20profile%20changed |
User role changed | User%20role%20changed |
User sent invite | User%20sent%20invite |
Workflow archived | Workflow%20archived |
Workflow cancelled | Workflow%20cancelled |
Workflow commented on | Workflow%20commented%20on |
Workflow created | Workflow%20created |
Workflow draft created | Workflow%20draft%20created |
Workflow draft publish request cancellation | Workflow%20draft%20publish%20request%20cancellation |
Workflow draft publish request | Workflow%20draft%20publish%20request |
Workflow edited | Workflow%20edited |
Workflow exported | Workflow%20exported |
Workflow imported | Workflow%20imported |
Workflow instance edited | Workflow%20instance%20edited |
Workflow instance permissions changed | Workflow%20instance%20permissions%20changed |
Workflow permissions changed | Workflow%20permissions%20changed |
Workflow started | Workflow%20started |
Workflow trigger created | Workflow%20trigger%20created |
Workflow trigger edited | Workflow%20trigger%20edited |
Workflow trigger removed | Workflow%20trigger%20removed |
Workflow unarchived | Workflow%20unarchived |
Workspace created | Workspace%20created |
Workspace removed | Workspace%20removed |
Workflow added to workspace | Workflow%20added%20to%20workspace |
Workflow removed from workspace | Workflow%20removed%20from%20workspace |
Workspace added to another workspace | Workspace%20added%20to%20another%20workspace |
Workspace removed from another workspace | Workspace%20removed%20from%20another%20workspace |
orderBy
How to order results by. At this time, the Audit logs api supports ordering by the createdAt
field, in either ascending or descending order.
Example | Description |
---|---|
https://[$team].pushbot.com/v1/[$team]/audit-logs?orderBy=createdAt%20DESC |
Return events, and order by createdAt in descending order. |
https://[$team].pushbot.com/v1/[$team]/audit-logs?action=Group%20deactivated&orderBy=createdAt%20ASC |
Return all events associated with a specific action type, and order by createdAt field in ascending order |
https://[$team].pushbot.com/v1/[$team]/audit-logs?userID=1091838acea028d0e8f0b0a08&orderBy=createdAt%20DESC |
Return all events associated with a specific userID and order by createdAt in descending order |
More Information on Exporting and Response Formats
By default, the API returns the content-type of application/json
and uses pagination. To make the response easier to import into your system, pagination can be disabled by constraining the timespan (startTime and endTime parameters), to a maximum of 24 hours. If done correctly, all matching events are returned in a single response.
For example, the following parameter returns results in a 12 hour window between 8AM and 8PM on September 6th.
https://[$team].pushbot.com/v1/[$team]/audit-logs?startTime=1630940400&endTime=1630983600
Additionally, you can output the response as a csv by adding the header Accept: text/csv
. If a CSV response is used, be sure to use the startTime and endTime parameters, as the maximum timespan of 24 hours is enforced since pagination is not supported with CSV.
Response Fields
The response body of an Audit log export uses a defined set of fields:
- When the response is in the default JSON format, the response is an object with a single
auditLogs
field. The field is an array whose contents will be individual JSON objects for each audit log event. - When using the CSV response format, each header is a field, and each row is a single audit log event.
Response Fields | Description |
---|---|
auditLogID |
Required. An internal identifier used to uniquely identify each audit log event. |
teamName |
Required. The teamName being queried. |
userID |
Required. The userID of the user initiating the event being logged. In most cases, the initiator detail is of minor consequence. For example, starting or cancelling a workflow, making a change to a team setting all only have one user involved. However, some events must keep the initiator in mind for accuracy, such as inviting a user to your team (the initiator is the person sending the invite), accepting an invite from your team (the initiator is the person receiving the invite and making a new account), and user permissions changes (the initiator is the person making the changes, not the person or persons being given access to a resource). If the client initiating the event is a guest user, and is not logged in to the PagerDuty Workflow Automation platform, the userID will be “10000000-0000-0000-0000-000000000000”. |
email |
The email of the user initiating the event being logged. If the client initiating the event is a guest user, and is not logged in to the PagerDuty Workflow Automation platform, the email will be “Guest”. |
clientIP |
The IP of the user initiating the event being logged at the time the event was logged. |
action |
Required. The action the event is executing. |
category |
Required. The category of the action the event is executing. Each action is contained by a single category. Categories are used for organization. You can see a list of categories on the View audit logs for your teams page. |
resourceIDs |
Required. A series of identifiers used to link to the resource being changed. From this data, a link to the resource that was changed can be constructed for further review, as long as that resource has not been deleted. |
resourceDisplayName |
A readable name that is used to easily identify the resource referenced by the resourceIDs. This should only be used for display purposes, and will not uniquely identify a resource. |
details |
Extra context on the changes that were made. This will only be provided for certain actions, and only in certain scenarios. For example, when making permissions changes to a resource, the users added and/or removed will be recorded here. |
createdAt |
Required. The UTC date and time of the event in ISO-8601 format. |
Example cURL requests
Below are some example requests in cURL format , assuming:
- a teamName of
teamname
- a time span between a startDate of midnight 2021-08-04 UTC (
1630728000000
) and an endDate of midnight 2021-08-05 UTC (1630814400000
) - an audit log API access token of
d47ce24726b8d74105b3e64a4cdbe6c8ecd4e5cfb2969a9809099962d6cb7b77
One User in CSV Format
curl \
--request GET \
--url "https://teamname.pushbot.com/v1/teams/teamname/audit-logs\
?startTime=1630728000000\ &endTime=1630814400000\ &userID=f8968f91-ccd7-41fb-a5f1-178f1b96eedc" \
--header 'Accept: text/csv' \
--header 'Authorization: Bearer d47ce24726b8d74105b3e64a4cdbe6c8ecd4e5cfb2969a9809099962d6cb7b77'
All But Two Users In CSV
curl \
--request GET \
--url "https://teamname.pushbot.com/v1/teams/teamname/audit-logs\
?startTime=1630728000000\
&endTime=1630814400000\ &excludedUserID=f8968f91-ccd7-41fb-a5f1-178f1b96eedc\ &excludedUserID=3ca5b643-8cac-4b1a-80c9-eafa6d9e1f73" \
--header 'Accept: text/csv' \
--header 'Authorization: Bearer d47ce24726b8d74105b3e64a4cdbe6c8ecd4e5cfb2969a9809099962d6cb7b77'
Only Failed Login Attempts In JSON
curl \
--request GET \
--url "https://teamname.pushbot.com/v1/teams/teamname/audit-logs\ ?startTime=1630728000000\
&endTime=1630814400000\ &action=User%20entered%20incorrect%20password" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer d47ce24726b8d74105b3e64a4cdbe6c8ecd4e5cfb2969a9809099962d6cb7b77'
Reverse Ordering In JSON
curl \
--request GET \
--url "https://teamname.pushbot.com/v1/teams/teamname/audit-logs\
?startTime=1630728000000\ &endTime=1630814400000\ &orderBy=createdAt%20ASC" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer d47ce24726b8d74105b3e64a4cdbe6c8ecd4e5cfb2969a9809099962d6cb7b77'
One User’s Workflow Instance Cancellations In JSON
curl \
--request GET \
--url "https://teamname.pushbot.com/v1/teams/teamname/audit-logs\
?startTime=1630728000000\ &endTime=1630814400000\ &userID=f8968f91-ccd7-41fb-a5f1-178f1b96eedc\ &action=Workflow%20cancelled" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer d47ce24726b8d74105b3e64a4cdbe6c8ecd4e5cfb2969a9809099962d6cb7b77'
Example response
Below is an example response with a content type of application/json ordered from youngest to oldest.
Example JSON response
{
"auditLogs": [
{
"auditLogID": "445a8c38-70a1-4673-84d9-52f4712d4cce", "teamName": "pagerduty",
"userID": "10000000-0000-0000-0000-000000000000", "email": "Guest",
"clientIP": "54.55.56.57",
"action": "Task webform completed",
"category": "Task",
"resourceIDs":
"Instance:e145c281-3e87-4ea8-9f8a-d0860f971712:Task:936bfbc8-9cab-422c-88c4 -7aee30b4d207",
"resourceDisplayName": "Webform", "details": null,
"createdAt": "2021-08-17T18:10:03.671Z"
}, {
"auditLogID": "abdb60da-942b-4f72-a316-ace85ed648da", "teamName": "pagerduty",
"userID": "10000000-0000-0000-0000-000000000000", "email": "Guest",
"clientIP": "54.55.56.57", "action": "Workflow started", "category": "Workflow", "resourceIDs":
"Workflow:15527b4c-bef5-4d7e-a4fc-aee55dc4e723:Instance:e145c281-3e87-4ea8- 9f8a-d0860f971712",
"resourceDisplayName": "Webform",
"details": "Started workflow from trigger Webform", "createdAt": "2021-08-17T18:09:22.586Z"
}, {
"auditLogID": "d4c367d2-b84d-4299-93b8-a0069621d5a9", "teamName": "pagerduty",
"userID": "10a379c3-15c5-4638-897e-fa97d76b4f1d", "email": "testuser@testdomain.com",
"clientIP": "112.113.114.115",
"action": "Workflow edited",
"category": "Workflow",
"resourceIDs": "Workflow:15527b4c-bef5-4d7e-a4fc-aee55dc4e723", "resourceDisplayName": "Test Workflow",
"details": "Edited ordering and dependencies of workflow steps",
"createdAt": "2021-08-17T18:08:56.632Z" },
{
"auditLogID": "c33ec6b7-9d95-46a5-929a-7938d935a85f", "teamName": "pagerduty",
"userID": "10a379c3-15c5-4638-897e-fa97d76b4f1d", "email": "testuser@testdomain.com",
"clientIP": "112.113.114.115",
"action": "Workflow edited",
"category": "Workflow",
"resourceIDs":
"Workflow:15527b4c-bef5-4d7e-a4fc-aee55dc4e723:Step:email-task", "resourceDisplayName": "Email Task",
"details": "Edited step Email Task",
"createdAt": "2021-08-17T18:08:55.780Z"
}, {
"auditLogID": "1dc3934e-1370-45cd-869d-e9de5e67a0e8", "teamName": "pagerduty",
"userID": "10a379c3-15c5-4638-897e-fa97d76b4f1d", "email": "testuser@testdomain.com",
"clientIP": "112.113.114.115", "action": "Workflow trigger removed", "category": "Workflow", "resourceIDs":
"Workflow:15527b4c-bef5-4d7e-a4fc-aee55dc4e723:Webhook:0840c8d3ea91ca1aa216 1c799f92d1aa3d97c910fc29ea7869e11871ccb46802",
"resourceDisplayName": "Test Scheduled Trigger", "details": "Removed Scheduled trigger", "createdAt": "2021-08-17T18:07:28.672Z"
}, {
"auditLogID": "17c30942-cea3-40f3-96cb-9f078f6890ee", "teamName": "pagerduty",
"userID": "10a379c3-15c5-4638-897e-fa97d76b4f1d", "email": "testuser@testdomain.com",
"clientIP": "112.113.114.115", "action": "Workflow cancelled", "category": "Workflow", "resourceIDs":
"Workflow:15527b4c-bef5-4d7e-a4fc-aee55dc4e723:Instance:95e59e4f-e642-4b6a- a4fd-373c9252bae3",
"resourceDisplayName": "Webform",
"details": null,
"createdAt": "2021-08-17T18:07:19.328Z" },
], "nextPageToken": ""
}
Get help with a problem or question
If something’s not working as expected, or you’re looking for suggestions, check through the options below.
How do I find a userID?
To find a user’s ID, use the users application table in the user ID
column, or from the user’s profile page by checking the page URL.
Thanks for your feedback
We update the Help Center daily, so expect changes soon.
Link Copied
Paste this URL anywhere to link straight to the section.