Skip to content

Audit Logs Export

Wherobots retains event logs for 90 days. To preserve logs beyond this period, export them using the Audit Logs REST API endpoint.

This guide discusses how to programmatically format requests to use the Audit Logs REST API endpoint.

If you'd prefer a detailed tutorial on the Audit Logs graphical user interface on Wherobots Cloud, see Audit Logs.

90 day log retention

Wherobots retains audit logs for a period of 90 days. To prevent data loss and ensure continuous access to your log records, we recommend implementing a scheduled script that utilizes this endpoint to export your logs and download the resulting CSV file. This proactive measure will safeguard your valuable audit data beyond the 90-day retention period.

Before you start

Before using Audit Logs, ensure that you have the following required resources:

What do I need before I get started?

Request body schema

Parameter Required Description
startTime Yes ✅ Only return events at or after
this time, expressed in ISO format
(e.g., YYYY-MM-DDTHH:mm:ssZ).
endTime Yes ✅ Only return events at or before
this time, expressed in ISO format.
searchTerm No ❌ A string to match against each
field in the event. If a substring match
succeeds on any field, thenthe event is included in the export.

ISO 8601 Date and Time Format

ISO format refers to the ISO 8601 standard(1), which defines a way to represent dates and times. This format ensures consistency and avoids ambiguity when exchanging date and time information.

  1. Here's a breakdown of the basic ISO 8601 format,YYYY-MM-DDTHH:mm:ss.sssZ:

    • YYYY: Year (e.g., 2025)
    • MM: Month (e.g., 02 for February)
    • DD: Day of the month (e.g., 20)
    • T: Separator indicating the start of the time component
    • HH: Hour (24-hour clock, e.g., 18 for 6 PM)
    • mm: Minute (e.g., 09)
    • ss: Second (e.g., 30)
    • sss: Optional fractional seconds (e.g., 123 for milliseconds)
    • Z: Indicates UTC (Coordinated Universal Time)

    Example:
    February 20, 2025 6:09PM PST in ISO 8601 format is 2025-02-20T18:09:00-08:00

    Timezone offset

    Include the timezone offset, -08:00, because Pacific Standard Time is UTC-8.

Route: GET /audit-logs/export

Example
1
2
3
4
5
6
curl -X GET \
    'https://api.cloud.wherobots.com/audit-logs/export \
    --data-urlencode 'startTime=2025-01-27T00:07:29Z' \
    --data-urlencode 'endTime=2025-01-27T00:07:29Z' \
    --data-urlencode 'searchTerm=example'
    -H 'X-API-KEY: YOUR-API-KEY' \

In line 6, replace YOUR-API-KEY with a Wherobots API key.

Explanation

Element/Parameter Description
-X GET Specifies that this is a GET request.
'https://api.cloud.wherobots.com/audit-logs/export' The URL endpoint for exporting audit logs.
?startTime= Sets the startTime parameter.
Replace the value
with your desired start time in
ISO 8601 format
(e.g., YYYY-MM-DDTHH:mm:ssZ).
&endTime= Sets the endTime parameter.
Replace the value with
your desired end
time in ISO 8601 format.
&searchTerm=example Sets the optional searchTerm parameter.
Replace example with your
desired search term.

Response body schema

The CSV will be in the following format:

Detail Description
event_time Timestamp when the event occurred.
user_id ID of user initiating request.
user_name Email address for human user, display name for service user.
user_agent Details about the software system initiating the request.
source_ip IP address where the request originated.
action_name Name of the action taken. For a full list of actions, see List of Auditable Events.
resource_name Name of the resource targeted by the action, if applicable.
resource_id ID of the resource targeted by the action, if applicable.
compute_region The compute region the event originated from, if applicable.

Response body example

Response example
1
2
event_id,event_time,action_name,user_id,user_name,user_agent,source_ip,resource_name,resource_id,compute_region
geteweunusi7pw,2025-02-20T20:48:10.355994+00:00,DestroyNotebook,43kh1a3snm0955,USER_IDENTIFIER,"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",IP_ADDRESS,,ev5a3dfnkoc354,

Response codes

The following table details a comprehensive listing of response codes encountered during a run's execution.

Response code Definition
200 Successful response
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not found
422 Validation Error
500 Internal Server Error

Limitations

  • API requests are limited to 100 requests per 5 seconds. This endpoint has no additional rate limits.
  • This feature can only be accessed by the Wherobots Organization's Admin. For more information on the Admin role, see Organization Roles.
  • Wherobots retains audit logs for a period of 90 days. To prevent data loss and ensure continuous access to your log records, we recommend implementing a scheduled script that utilizes this endpoint to export your logs and download the resulting CSV file. This proactive measure will safeguard your valuable audit data beyond the 90-day retention period.