---
title: List Turnstile Widgets
---

[Skip to content](#_top)

[API Reference](https://developers.cloudflare.com/api/typescript)

[Turnstile](https://developers.cloudflare.com/api/typescript/resources/turnstile)

[Widgets](https://developers.cloudflare.com/api/typescript/resources/turnstile/subresources/widgets)

Copy Markdown

Open in **Claude**Open in **ChatGPT**Open in **Cursor**

---

**Copy Markdown****View as Markdown**

# List Turnstile Widgets

client.turnstile.widgets.list(WidgetListParams {account\_id, direction, filter, 3 more } params, RequestOptionsoptions?): V4PagePaginationArray< [WidgetListResponse](<https://developers.cloudflare.com/api/typescript/resources/turnstile#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)>) {bot\_fight\_mode, clearance\_level, created\_on, 10 more } >

GET/accounts/{account\_id}/challenges/widgets

Lists Turnstile widgets for an account.

##### Security

<details>

<summary>API Token</summary>



The preferred authorization scheme for interacting with the Cloudflare API. <a href="https://developers.cloudflare.com/fundamentals/api/get-started/create-token/">Create a token</a>.

**Example:**<code>Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY</code>

</details>

<details>

<summary>API Email + API Key</summary>



The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

**Example:**<code>X-Auth-Email: user@example.com</code>

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

**Example:**<code>X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194</code>

</details>

##### Accepted Permissions (at least one required)

`Turnstile Sites Write``Turnstile Sites Read``Account Settings Write``Account Settings Read`

##### ParametersExpand Collapse

<details>

<summary>

params: WidgetListParams {account\_id, direction, filter, 3 more }

</summary>

account\_id: string

Path param: Identifier

maxLength32

<a href="#(resource)%20turnstile.widgets%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20account_id">Link to this property</a>

<details>

<summary>

direction?: "asc"| "desc"

Query param: Direction to order widgets.

</summary>

One of the following:

"asc"

<a href="#(resource)%20turnstile.widgets%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20direction%20%3E%20(schema)%20%3E%20(member)%200">Link to this property</a>

"desc"

<a href="#(resource)%20turnstile.widgets%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20direction%20%3E%20(schema)%20%3E%20(member)%201">Link to this property</a>

</details>

<a href="#(resource)%20turnstile.widgets%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20direction">Link to this property</a>

filter?: string

Query param: Filter widgets by field. The <code>name</code> field uses case-insensitive substring matching; <code>sitekey</code> uses exact matching. Format: <code>field:value</code>

Supported fields:

- <code>name</code> - Filter by widget name (e.g., <code>filter=name:login-form</code>)
- <code>sitekey</code> - Filter by sitekey (e.g., <code>filter=sitekey:0x4AAA</code>)

Returns 400 Bad Request if the field is unsupported or format is invalid. An empty filter value returns all results.

<a href="#(resource)%20turnstile.widgets%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20filter">Link to this property</a>

<details>

<summary>

order?: "id"| "sitekey"| "name"| 2 more

Query param: Field to order widgets by.

</summary>

One of the following:

"id"

<a href="#(resource)%20turnstile.widgets%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20order%20%3E%20(schema)%20%3E%20(member)%200">Link to this property</a>

"sitekey"

<a href="#(resource)%20turnstile.widgets%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20order%20%3E%20(schema)%20%3E%20(member)%201">Link to this property</a>

"name"

<a href="#(resource)%20turnstile.widgets%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20order%20%3E%20(schema)%20%3E%20(member)%202">Link to this property</a>

"created\_on"

<a href="#(resource)%20turnstile.widgets%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20order%20%3E%20(schema)%20%3E%20(member)%203">Link to this property</a>

"modified\_on"

<a href="#(resource)%20turnstile.widgets%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20order%20%3E%20(schema)%20%3E%20(member)%204">Link to this property</a>

</details>

<a href="#(resource)%20turnstile.widgets%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20order">Link to this property</a>

page?: number

Query param: Page number of paginated results.

minimum1

<a href="#(resource)%20turnstile.widgets%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20page">Link to this property</a>

per\_page?: number

Query param: Number of items per page.

maximum1000

minimum5

<a href="#(resource)%20turnstile.widgets%20%3E%20(method)%20list%20%3E%20(params)%20default%20%3E%20(param)%20per_page">Link to this property</a>

</details>

[Link to this property](<#(resource)%20turnstile.widgets%20%3E%20(method)%20list%20%3E%20(params)%20default>)

##### ReturnsExpand Collapse

<details>

<summary>

WidgetListResponse {bot\_fight\_mode, clearance\_level, created\_on, 10 more }

A Turnstile Widgets configuration as it appears in listings

</summary>

bot\_fight\_mode: boolean

If bot\_fight\_mode is set to <code>true</code>, Cloudflare issues computationally expensive challenges in response to malicious bots (ENT only).

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20bot_fight_mode">Link to this property</a>

<details>

<summary>

clearance\_level: "no\_clearance"| "jschallenge"| "managed"| "interactive"

If Turnstile is embedded on a Cloudflare site and the widget should grant challenge clearance, this setting can determine the clearance level to be set

</summary>

One of the following:

"no\_clearance"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20clearance_level%20%3E%20(member)%200">Link to this property</a>

"jschallenge"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20clearance_level%20%3E%20(member)%201">Link to this property</a>

"managed"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20clearance_level%20%3E%20(member)%202">Link to this property</a>

"interactive"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20clearance_level%20%3E%20(member)%203">Link to this property</a>

</details>

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20clearance_level">Link to this property</a>

created\_on: string

When the widget was created.

formatdate-time

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20created_on">Link to this property</a>

domains: Array&lt;<a href="https://developers.cloudflare.com/api/typescript/resources/turnstile#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_domain%20%3E%20(schema)">WidgetDomain</a>&gt;

maxLength10

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20domains">Link to this property</a>

ephemeral\_id: boolean

Return the Ephemeral ID in /siteverify (ENT only).

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20ephemeral_id">Link to this property</a>

<details>

<summary>

mode: "non-interactive"| "invisible"| "managed"

Widget Mode

</summary>

One of the following:

"non-interactive"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20mode%20%3E%20(member)%200">Link to this property</a>

"invisible"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20mode%20%3E%20(member)%201">Link to this property</a>

"managed"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20mode%20%3E%20(member)%202">Link to this property</a>

</details>

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20mode">Link to this property</a>

modified\_on: string

When the widget was modified.

formatdate-time

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20modified_on">Link to this property</a>

name: string

Human readable widget name. Not unique. Cloudflare suggests that you set this to a meaningful string to make it easier to identify your widget, and where it is used.

maxLength254

minLength1

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20name">Link to this property</a>

offlabel: boolean

Do not show any Cloudflare branding on the widget (ENT only).

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20offlabel">Link to this property</a>

<details>

<summary>

region: "world"| "china"

Region where this widget can be used. This cannot be changed after creation.

</summary>

One of the following:

"world"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20region%20%3E%20(member)%200">Link to this property</a>

"china"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20region%20%3E%20(member)%201">Link to this property</a>

</details>

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20region">Link to this property</a>

sitekey: string

Unique identifier for a Turnstile widget.

maxLength32

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20sitekey">Link to this property</a>

<details>

<summary>

deployed\_via?: "wrangler"| "dashboard"| "spin"| 2 more

Origin that created this widget, recorded at creation time and immutable afterward. Server-derived from the create request; not client-settable. Omitted from the response for widgets created before this field existed.

</summary>

One of the following:

"wrangler"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20deployed_via%20%3E%20(member)%200">Link to this property</a>

"dashboard"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20deployed_via%20%3E%20(member)%201">Link to this property</a>

"spin"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20deployed_via%20%3E%20(member)%202">Link to this property</a>

"api"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20deployed_via%20%3E%20(member)%203">Link to this property</a>

"unknown"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20deployed_via%20%3E%20(member)%204">Link to this property</a>

</details>

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20deployed_via">Link to this property</a>

<details>

<summary>

last\_modified\_via?: "wrangler"| "dashboard"| "spin"| 2 more

Origin of the most recent mutation (create, update, delete, or secret rotation). Server-derived; not client-settable. Omitted for widgets last mutated before this field existed.

</summary>

One of the following:

"wrangler"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20last_modified_via%20%3E%20(member)%200">Link to this property</a>

"dashboard"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20last_modified_via%20%3E%20(member)%201">Link to this property</a>

"spin"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20last_modified_via%20%3E%20(member)%202">Link to this property</a>

"api"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20last_modified_via%20%3E%20(member)%203">Link to this property</a>

"unknown"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20last_modified_via%20%3E%20(member)%204">Link to this property</a>

</details>

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)%20%3E%20(property)%20last_modified_via">Link to this property</a>

</details>

[Link to this property](<#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_list_response%20%3E%20(schema)>)

### List Turnstile Widgets

TypeScript

HTTPTypeScriptPythonGoTerraform

```
import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const widgetListResponse of client.turnstile.widgets.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  console.log(widgetListResponse.ephemeral_id);
}
```

200 example

```
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": [
    {
      "bot_fight_mode": false,
      "clearance_level": "interactive",
      "created_on": "2014-01-01T05:20:00.123123Z",
      "domains": [
        "203.0.113.1",
        "cloudflare.com",
        "blog.example.com"
      ],
      "ephemeral_id": false,
      "mode": "invisible",
      "modified_on": "2014-01-01T05:20:00.123123Z",
      "name": "blog.cloudflare.com login form",
      "offlabel": false,
      "region": "world",
      "sitekey": "0x4AAF00AAAABn0R22HWm-YUc",
      "deployed_via": "wrangler",
      "last_modified_via": "dashboard"
    }
  ],
  "result_info": {
    "count": 1,
    "page": 1,
    "per_page": 20,
    "total_count": 2000
  }
}
```

##### Returns Examples

200 example

```
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": [
    {
      "bot_fight_mode": false,
      "clearance_level": "interactive",
      "created_on": "2014-01-01T05:20:00.123123Z",
      "domains": [
        "203.0.113.1",
        "cloudflare.com",
        "blog.example.com"
      ],
      "ephemeral_id": false,
      "mode": "invisible",
      "modified_on": "2014-01-01T05:20:00.123123Z",
      "name": "blog.cloudflare.com login form",
      "offlabel": false,
      "region": "world",
      "sitekey": "0x4AAF00AAAABn0R22HWm-YUc",
      "deployed_via": "wrangler",
      "last_modified_via": "dashboard"
    }
  ],
  "result_info": {
    "count": 1,
    "page": 1,
    "per_page": 20,
    "total_count": 2000
  }
}
```