# List registered agents (https://developer.godaddy.com/en/docs/references/rest/ans/list-registered-agents)

---
title: List registered agents
description: Lists registered agents using query parameters.
full: true
---

Full description

Lists registered agents using query parameters. Returns a ranked collection; follow pagination links\[].href for subsequent pages.

## GET /v1/ans/registered-agents

List registered agents

Lists registered agents using query parameters. Returns a ranked collection; follow pagination links[].href for subsequent pages.

### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `profile` | string | no | Scoring profile name (default: `default`). |
| `query` | string | no | Optional search query string. If omitted and no filters are provided, the API returns all agents except `REVOKED` by default. When `statuses` is explicitly provided, the API uses only the provided status values. Max length is 256 characters by default. When `keywordExtraction=true`, max length is 4096 characters. |
| `keywordExtraction` | boolean | no | When true, extracts keywords from the query text before searching. Increases max query length from 256 to 4096 characters. Requires `query` to be non-empty. |
| `keywordAlgorithm` | string | no | Keyword extraction algorithm to use when `keywordExtraction=true`. |
| `pageSize` | integer | no | Number of results per page (1-100). |
| `pageToken` | string | no | Opaque token from a previous response `links[].href` relation (`rel=next` or `rel=prev`). |
| `pageTokenDirection` | string | no | Optional token direction when `pageToken` is set. Only valid when `pageToken` is provided. Requests that send `pageTokenDirection` without `pageToken` return `422 INVALID_REQUEST`. |
| `totalRequired` | boolean | no | When true, include `totalItems` and `totalPages` in the response envelope. |
| `providerIds` | array | no | Filter by provider IDs. |
| `statuses` | array | no | Filter by lifecycle statuses. When omitted, default behavior excludes `REVOKED`. |
| `agentDomains` | array | no | Agent host domain-family filters. Each value matches apex plus subdomains. |
| `protocols` | array | no | Filter by endpoint protocols. |
| `transports` | array | no | Filter by endpoint transports. |
| `tags` | array | no | Filter by endpoint function tags (`endpoints.functions.tags`). |
| `capabilities` | array | no | Filter by function names (`endpoints.functions.name`). |
| `scoring.pillarWeights.identity` | integer | no | Identity pillar weight override. |
| `scoring.pillarWeights.integrity` | integer | no | Integrity pillar weight override. |
| `scoring.thresholds.identity` | integer | no | Identity pillar threshold filter. |
| `scoring.thresholds.integrity` | integer | no | Integrity pillar threshold filter. |

### Header parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `X-Request-Id` | string <uuid> | no | Optional request identifier propagated across services. |

### Responses

**200** — Successful response containing a paged list of registered agents

Content-Type: `*/*`

Schema:

- schema reference: `#/components/schemas/AnsRegisteredAgentsList`

**400** — Malformed request syntax or invalid encoding

Content-Type: `*/*`

Schema:

- schema reference: `#/components/schemas/ErrorResponse`

**401** — Authentication info not sent or is invalid

Content-Type: `*/*`

Schema:

- schema reference: `#/components/schemas/ErrorResponse`

**403** — Authenticated user is not allowed access

Content-Type: `*/*`

Schema:

- schema reference: `#/components/schemas/ErrorResponse`

**422** — Request validation failed

Content-Type: `*/*`

Schema:

- schema reference: `#/components/schemas/ErrorResponse`

**429** — Too many requests - rate limit exceeded

Content-Type: `*/*`

Schema:

- schema reference: `#/components/schemas/ErrorResponse`

**500** — Internal server error

Content-Type: `*/*`

Schema:

- schema reference: `#/components/schemas/ErrorResponse`

**502** — Bad gateway or failed dependency

Content-Type: `*/*`

Schema:

- schema reference: `#/components/schemas/ErrorResponse`

**503** — Service is temporarily unavailable

Content-Type: `*/*`

Schema:

- schema reference: `#/components/schemas/ErrorResponse`

**504** — Gateway or dependency timeout

Content-Type: `*/*`

Schema:

- schema reference: `#/components/schemas/ErrorResponse`