Retrieve Log Events Using the Management API
You can use the Management API to retrieve up to 100 log events per request using the /get_logs endpoint, which supports two types of consumption:
By checkpoint: Recommended if you want to export log events to the external data analytics service.
By search criteria: Used by the Dashboard.
Logs stored by Auth0 are subject to a retention period that is based on your Auth0 subscription. To learn more, read Log Data Retention.
You can also use these endpoints to look for logs:
/api/v2/logs/{id}
: Retrieves the single log entry associated with the provided log ID./api/v2/users/{user_id}/logs
: Retrieves log events for a specific user ID.
Retrieve logs by checkpoint
This method allows you to retrieve log events newer than a given log_id
. It
is commonly used to send your Logs to an external system, such as Splunk, Datadog,
Application Insights, Mixpanel, and more.
To search by checkpoint, use the following parameters:
Parameter | Description |
---|---|
from |
Log event ID to start retrieving logs. You can limit the amount of logs using the take parameter. |
take |
The total amount of entries to retrieve when using the from parameter. |
Any parameter other than from
and take
will be ignored. The logs are ordered by the log_id
.
Semantics
Retrieving logs by checkpoint have the following semantics:
All logs available to your role's permissions will be returned
The logs are ordered by the
log_id
, rather than event generation time, to prevent skipping past records due to Auth0 system delaysPagination is unbounded, meaning there is no limit, in contrast to the
1,000
record limit when retrieving logs by search criteria
Pagination
When retrieving logs by checkpoint, only the first request should be made
manually. Each subsequent request should be made using the next
relation URL
inside of the Link
header. This simplifies the work for integrating with the
API, and allows Auth0 to make optimizations without impacting the customer
experience.
Example
Let's assume your tenant name in the us
is acme
. To start retrieving records by
checkpoint:
Grab the
log_id
from any log in your system. Example:90020211201185132572079310688835925971249535794074878050
.Make a request to
https://TENANT_NAME.LOCALITY.auth0.com/api/v2/logs?from=LOG_ID&take=100
to request the next100
logs newer than the givenLOG_ID
.The HTTP response will contain
A JSON array of
0
to100
logs newer than the givenLOG_ID
An HTTP
Link
header with anext
relation
If the result set is empty you will receive an empty array, and the
next
relation will match the same URL you used in the most recent request
Retrieve logs by search criteria
This method allows you to retrieve log events that match the specified search criteria or, if no criteria is used, lists all events. To search by criteria use the following parameters:
Parameter | Description |
---|---|
q |
Search criteria using Query String Syntax. |
page |
The zero-based page number. |
per_page |
The number of entries per page. |
sort |
The field to use for sorting. Use field:order , where order is 1 for ascending and -1 for descending. For example date:-1 . |
fields |
A comma-separated field list to include or exclude (depending on include_fields ) from the result. Leave empty to retrieve all fields. |
include_fields |
true if the fields specified are to be included in the result, false otherwise. Defaults to true . |
To see a list of fields and sort parameters that can be used in the search query, read Log Search Query Syntax.
Limitations
Besides the limitation of 100 log events per request to retrieve logs, you may only paginate through up to 1,000 search results.
If you get the error 414 Request-URI Too Large
this means that your query string is larger than the supported length. In this case, refine your search.
Private Cloud search field limitations
The following fields are searchable only for Private Cloud:
user
connection
application
type
ip
Use double quotes for exact searches (e.g., application:"test"
will search for all log events specific to the application named test
, but application:test
will search log events for applications with "test" in their name.