docs/en/latest/plugins/request-id.md

title: request-id keywords:

Apache APISIX
API Gateway
Request ID description: The request-id Plugin adds a unique ID to each request proxied through APISIX, which can be used to track API requests.

Description

The request-id Plugin adds a unique ID to each request proxied through APISIX, which can be used to track API requests. If a request carries an ID in the header corresponding to header_name, the Plugin will use the header value as the unique ID and will not overwrite with the automatically generated ID.

Attributes

Name	Type	Required	Default	Valid values	Description
header_name	string	False	“X-Request-Id”		Name of the header that carries the request unique ID. Note that if a request carries an ID in the `header_name` header, the Plugin will use the header value as the unique ID and will not overwrite it with the generated ID.
include_in_response	boolean	False	true		If true, include the generated request ID in the response header, where the name of the header is the `header_name` value.
algorithm	string	False	“uuid”	[“uuid”,“nanoid”,“range_id”,“ksuid”]	Algorithm used for generating the unique ID. When set to `uuid` , the Plugin generates a universally unique identifier. When set to `nanoid`, the Plugin generates a compact, URL-safe ID. When set to `range_id`, the Plugin generates a sequential ID with specific parameters. When set to `ksuid`, the Plugin generates a sequential ID with timestamp and random number.
range_id	object	False			Configuration for generating a request ID using the `range_id` algorithm.
range_id.char_set	string	False	“abcdefghijklmnopqrstuvwxyzABCDEFGHIGKLMNOPQRSTUVWXYZ0123456789”	minimum length 6	Character set used for the `range_id` algorithm.
range_id.length	integer	False	16	>=6	Length of the generated ID for the `range_id` algorithm.

Examples

The examples below demonstrate how you can configure request-id in different scenarios.

:::note

You can fetch the admin_key from config.yaml and save to an environment variable with the following command:

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

:::

Attach Request ID to Default Response Header

The following example demonstrates how to configure request-id on a Route which attaches a generated request ID to the default X-Request-Id response header, if the header value is not passed in the request. When the X-Request-Id header is set in the request, the Plugin will take the value in the request header as the request ID.

Create a Route with the request-id Plugin using its default configurations (explicitly defined):

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "plugins": {
      "request-id": {
        "header_name": "X-Request-Id",
        "include_in_response": true,
        "algorithm": "uuid"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

Send a request to the Route:

curl -i "http://127.0.0.1:9080/anything"

You should receive an HTTP/1.1 200 OK response and see the response includes the X-Request-Id header with a generated ID:

X-Request-Id: b9b2c0d4-d058-46fa-bafc-dd91a0ccf441

Send a request to the Route with a custom request ID in the header:

curl -i "http://127.0.0.1:9080/anything" -H 'X-Request-Id: some-custom-request-id'

You should receive an HTTP/1.1 200 OK response and see the response includes the X-Request-Id header with the custom request ID:

X-Request-Id: some-custom-request-id

Attach Request ID to Custom Response Header

The following example demonstrates how to configure request-id on a Route which attaches a generated request ID to a specified header.

Create a Route with the request-id Plugin to define a custom header that carries the request ID and include the request ID in the response header:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "plugins": {
      "request-id": {
        "header_name": "X-Req-Identifier",
        "include_in_response": true
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

Send a request to the route:

curl -i "http://127.0.0.1:9080/anything"

You should receive an HTTP/1.1 200 OK response and see the response includes the X-Req-Identifier header with a generated ID:

X-Req-Identifier: 1c42ff59-ee4c-4103-a980-8359f4135b21

Hide Request ID in Response Header

The following example demonstrates how to configure request-id on a Route which attaches a generated request ID to a specified header. The header containing the request ID should be forwarded to the Upstream service but not returned in the response header.

Create a Route with the request-id Plugin to define a custom header that carries the request ID and not include the request ID in the response header:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "plugins": {
      "request-id": {
        "header_name": "X-Req-Identifier",
        "include_in_response": false
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

Send a request to the Route:

curl -i "http://127.0.0.1:9080/anything"

You should receive an HTTP/1.1 200 OK response not and see X-Req-Identifier header among the response headers. In the response body, you should see:

{
  "args": {},
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Host": "127.0.0.1",
    "User-Agent": "curl/8.6.0",
    "X-Amzn-Trace-Id": "Root=1-6752748c-7d364f48564508db1e8c9ea8",
    "X-Forwarded-Host": "127.0.0.1",
    "X-Req-Identifier": "268092bc-15e1-4461-b277-bf7775f2856f"
  },
  ...
}

This shows the request ID is forwarded to the Upstream service but not returned in the response header.

Use `nanoid` Algorithm

The following example demonstrates how to configure request-id on a Route and use the nanoid algorithm to generate the request ID.

Create a Route with the request-id Plugin as such:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "plugins": {
      "request-id": {
        "algorithm": "nanoid"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

Send a request to the Route:

curl -i "http://127.0.0.1:9080/anything"

You should receive an HTTP/1.1 200 OK response and see the response includes the X-Req-Identifier header with an ID generated using the nanoid algorithm:

X-Request-Id: kepgHWCH2ycQ6JknQKrX2

Use `ksuid` Algorithm

The following example demonstrates how to configure request-id on a Route and use the ksuid algorithm to generate the request ID.

Create a Route with the request-id Plugin as such:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "plugins": {
      "request-id": {
        "algorithm": "ksuid"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

Send a request to the Route:

curl -i "http://127.0.0.1:9080/anything"

You should receive an HTTP/1.1 200 OK response and see the response includes the X-Request-Id header with an ID generated using the ksuid algorithm:

X-Request-Id: 325ghCANEKjw6Jsfejg5p6QrLYB

If the ksuid is installed, this ID can be viewed through ksuid -f inspect 325ghCANEKjw6Jsfejg5p6QrLYB:

REPRESENTATION:

    String: 325ghCANEKjw6Jsfejg5p6QrLYB
    Raw: 15430DBBD7F68AD7CA0AE277772AB36DDB1A3C13

COMPONENTS:

    Time: 2025-09-01 16:39:23 +0800 CST
    Timestamp: 356715963
    Payload: D7F68AD7CA0AE277772AB36DDB1A3C13

Attach Request ID Globally and on a Route

The following example demonstrates how to configure request-id as a global Plugin and on a Route to attach two IDs.

Create a global rule for the request-id Plugin which adds request ID to a custom header:

curl -i "http://127.0.0.1:9180/apisix/admin/global_rules" -X PUT -d '{
  "id": "rule-for-request-id",
  "plugins": {
    "request-id": {
      "header_name": "Global-Request-ID"
    }
  }
}'

Create a Route with the request-id Plugin which adds request ID to a different custom header:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "request-id-route",
    "uri": "/anything",
    "plugins": {
      "request-id": {
        "header_name": "Route-Request-ID"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

Send a request to the Route:

curl -i "http://127.0.0.1:9080/anything"

You should receive an HTTP/1.1 200 OK response and see the response includes the following headers:

Global-Request-ID: 2e9b99c1-08ed-4a74-b347-49c0891b07ad
Route-Request-ID: d755666b-732c-4f0e-a30e-a7a71ace4e26

Description

Attributes

Examples

Attach Request ID to Default Response Header

Attach Request ID to Custom Response Header

Hide Request ID in Response Header

Use nanoid Algorithm

Use ksuid Algorithm

Attach Request ID Globally and on a Route

Use `nanoid` Algorithm

Use `ksuid` Algorithm