---
title: "List ratelimit namespaces"
method: POST
path: "/v2/ratelimit.listNamespaces"
tags: ["ratelimit"]
---

# List ratelimit namespaces

`POST /v2/ratelimit.listNamespaces`

## Request

- Base URL: `https://api.unkey.com`
- URL: `https://api.unkey.com/v2/ratelimit.listNamespaces`
- Auth: HTTP bearer

Retrieve a paginated list of the rate limit namespaces in your workspace.

Use this to find the namespaces your services rate limit against, for example to build an admin view or to look up a namespace ID. Results are ordered newest first and returned in pages. When `hasMore` is true, pass the returned `cursor` to fetch the next page.

Deleted namespaces are not returned. The list contains only the namespaces your root key can read.

**Required Permissions**

Your root key must have one of the following permissions:
- `unkey:v1:<workspace_id>:projects/*/ratelimits/namespaces/*#read` (to read any namespace)
- `unkey:v1:<workspace_id>:projects/<project_id>/ratelimits/namespaces/<namespace_id>#read` (to read a specific namespace)

## Request body

- V2RatelimitListNamespacesRequestBody
  - `limit` integer: Maximum number of namespaces to return per request. Omit this field to receive up to 100 namespaces.
  - `cursor` string: Pagination cursor from a previous response to fetch the next page. Use when `hasMore: true` in the previous response. Omit this field to start from the first page.
  - `search` string: Free-form text to filter namespaces. Returns namespaces whose ID or name contains the search string. Matching is case-insensitive. Omit this field to list every namespace.

## Response `200`

Successfully retrieved a page of namespaces. Use the pagination cursor for additional results when `hasMore: true`.

- V2RatelimitListNamespacesResponseBody
  - `meta` Meta, required: Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required: A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` RatelimitNamespace[], required: Namespaces in the workspace, newest first.
    - `id` string, required: The unique identifier of the namespace, generated by Unkey.
    - `name` string, required: The name of the namespace, unique within your workspace. Pass it as `namespace` to `ratelimit.limit` and the override endpoints.
    - `createdAt` integer, required: Unix timestamp in milliseconds when the namespace was created.
    - `updatedAt` integer: Unix timestamp in milliseconds when the namespace was last updated. Omitted if the namespace has never been updated.
  - `pagination` Pagination, required: Pagination metadata for list endpoints. Provides information necessary to traverse through large result sets efficiently using cursor-based pagination.
    - `cursor` string: Opaque pagination token for retrieving the next page of results. Include this exact value in the cursor field of subsequent requests. Cursors are temporary and may expire after extended periods.
    - `hasMore` boolean, required: Indicates whether additional results exist beyond this page. When true, use the cursor to fetch the next page. When false, you have reached the end of the result set.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `429`: Too Many Requests
- `500`: Internal server error

## Changes

- **2026-10-13** `453c75597bad`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/unkeyed/apis/unkey-api/changes/v2/ratelimit.listNamespaces/post.md)

---

[API](https://skmtc.dev/unkeyed/apis/unkey-api.md) - [All operations](https://skmtc.dev/unkeyed/apis/unkey-api/llms.txt) - [OpenAPI document](https://skmtc.dev/unkeyed/apis/unkey-api/revisions/6fbaa27f19e0?raw)