# Search the ANSName Registry with flexible criteria (https://developer.godaddy.com/en/docs/references/rest/ans/search-ans-name)

---
title: Search the ANSName Registry with flexible criteria
description: >-
  Searches the Agent Name Service registry using flexible criteria such as
  partial agent names, agent host domains, and version ranges.
full: true
---

Full description

\| Searches the Agent Name Service registry using flexible criteria such as partial agent names, agent host domains, and version ranges. The search can return multiple matching agents along with their metadata and endpoints. Results are paginated to handle large datasets efficiently.

## GET /v1/agents

Search the ANSName Registry with flexible criteria

Searches the Agent Name Service registry using flexible criteria such as
partial agent names, agent host domains, and version ranges. The search
can return multiple matching agents along with their metadata and endpoints.
Results are paginated to handle large datasets efficiently.


### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `agentDisplayName` | string | no | Agent display name (partial matching supported) |
| `version` | string | no | Target version (flexible matching supported) |
| `agentHost` | string | no | Target agent host domain |
| `protocol` | string | no | Target protocol (optional filter) - valid values are 'A2A', 'MCP', 'HTTP-API' |
| `limit` | integer | no | Maximum number of results to return (default 20, max 100) |
| `offset` | integer | no | Number of results to skip for pagination (default 0) |
| `status` | array | no | Filter by agent lifecycle status. Can specify multiple values. Defaults to ACTIVE when not provided. Use 'ALL' to return agents of any status. If 'ALL' is included with other status values, only 'ALL' is applied. |

### Responses

**200** — Search completed successfully (may return empty results if no agents match criteria)

Content-Type: `application/json`

Schema:

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

**401** — Authentication failed

Content-Type: `application/json`

Schema:

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

**403** — Authorization failed

Content-Type: `application/json`

Schema:

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

**422** — Invalid search parameters (e.g., invalid pagination values)

Content-Type: `application/json`

Schema:

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

**500** — Internal server error

Content-Type: `application/json`

Schema:

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