Request logs

Deel records every request made to the public API with one of your organization’s tokens and keeps the records for 15 days. Use them to find out why a request failed, to see which tokens are in use, and to give Deel Support the exact request to look at.

What is recorded

One record is kept per REST API request, SCIM API request, or MCP tool call, including rejected responses, such as 401, 403, 404, and 429.

Each record details the request id, the timestamp in UTC, the HTTP method, route, and path, the status, the total and upstream durations, the source, the token, the client IP address, the user agent, the API version, the response size, and the error. The API reference documents every field.

Notes on additional fields:

When you retrieve a single request, the record also includes a gateway_message (what the outcome means in plain language) and a hint (what to do about it). See Common gateway messages.

What is never recorded

• Request and response bodies
• Request and response headers, including Authorization
• Query strings: path stops at the ?

The logs describe that a request happened and how it ended, not what it carried. Deel does not process request logs with AI.

Retention and access

Deel keeps records for 15 days and then deletes them. There is no archive, and a query window cannot span more than 15 days.

To read the logs through the API, CLI, or MCP, a token needs the api-logs:read scope, which is never granted by default. Select it when you create the token or request it during the OAuth2 authorization.

The logs endpoints are limited to 60 requests in any rolling 60-second window per organization, in addition to the general rate limits, so short bursts are allowed. Excess requests receive a 429 response. Each list request returns up to 100 records, so you can read up to 6,000 records per minute.

Developer Center

Open the Logs tab in the Developer Center.

• API requests lists the organization’s requests, newest first, covering a range of 15 minutes to 15 days. You can:
  • Filter by X-Request-ID, token ID, route, or status (2xx, 4xx, 5xx).
  • Select a request to open its details: the gateway message and hint, request ID (with a copy action), token, source, calling client, source IP, API version, and response size.
  • Turn on Live to refresh the list every 10 seconds.
• Token activity lists the tokens seen in the time range with their calls, errors, last use, and last IP, and shows a per-day breakdown for each token.

API

The full parameter and response schemas are in the API reference, section Logs.

Filters and pagination

The requests endpoints filter by request id, token, route, path, method, status, status class, and source; the tokens endpoint filters by label or id with search. The requests endpoints accept a time range as from and to, in ISO 8601 format. Without from, the range covers the 24 hours before to. Without to, the range ends at the current timestamp. A range longer than 15 days is cut to 15 days.

List responses have the shape {"data": [...], "page": {"cursor": "...", "has_next_page": true}}. Pass page.cursor back as cursor until has_next_page is false. Set the page size with limit, from 1 to 100; the default is 50.

Examples

The examples read the token from the DEEL_API_TOKEN environment variable.

List requests

4xx responses in the last 24 hours (the default range), 100 per page:

curl --get 'https://api.letsdeel.com/rest/v2/logs/requests' \
  --header "Authorization: Bearer $DEEL_API_TOKEN" \
  --data-urlencode 'status_class=4xx' \
  --data-urlencode 'limit=100'

To run other queries, change the --data-urlencode lines:

Retrieve one request

The request a client reported, by its X-Request-ID. The response adds the explanation:

curl 'https://api.letsdeel.com/rest/v2/logs/requests/5f1c2a8e9b3d4c7a1e2f3a4b' \
  --header "Authorization: Bearer $DEEL_API_TOKEN"

Get a summary

Counts and latency for the last 24 hours:

curl 'https://api.letsdeel.com/rest/v2/logs/requests/summary' \
  --header "Authorization: Bearer $DEEL_API_TOKEN"

CLI

Read the logs with deel logs. The commands print JSON, so you can filter the output or pipe it to another tool.

The flags take the same filters as the API parameters. The CLI’s own calls are logged like any other request, with the CLI recorded as the calling client.

MCP

The four endpoints are also available as tools on the Deel MCP server, so an AI assistant connected to Deel can answer questions such as “why did the payroll sync fail this morning?” from the logs.

Tool calls are recorded in the logs with source set to mcp. To grant scopes to an MCP client, see Authorization. For the full list of tools, see the Tools reference.

Using the request id with support

Every API response includes its request ID in the X-Request-ID header. Error responses also include it in the body, as request.api_req_id. In log records it appears as request_id, and the Developer Center shows it for each logged request.

When you contact Deel Support about a failed request, include:

1. The request id.
2. The timestamp in UTC, as shown in the log.
3. What you expected to happen.

With the request id, Support can locate the exact request without you sharing the payload.

Handling log data

When an AI agent reads the logs for you through the CLI or MCP, it does so with your organization’s token, under your organization’s data policies.

Common gateway messages

The gateway_message and hint of a request depend on its status and, where present, its error.code. The most common outcomes:

You can retry 5xx responses to GET and DELETE requests unconditionally. For POST and PATCH, follow the error handling guidance.

Next steps