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 delays

  • Pagination 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:

  1. Grab the log_id from any log in your system. Example: 90020211201185132572079310688835925971249535794074878050.

  2. Make a request to https://TENANT_NAME.LOCALITY.auth0.com/api/v2/logs?from=LOG_ID&take=100 to request the next 100 logs newer than the given LOG_ID.

  3. The HTTP response will contain

    1. A JSON array of 0 to 100 logs newer than the given LOG_ID

    2. An HTTP Link header with a next relation

  4. 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.

Learn more