# Search (https://developer.godaddy.com/en/docs/references/rest/ans/search)

***

title: Search
description: ''
full: true
\_openapi:
method: GET
toc:

* depth: 2
  title: Search the ANSName Registry with flexible criteria
  url: '#search-the-ansname-registry-with-flexible-criteria'
  structuredData:
  headings:
  * content: Search the ANSName Registry with flexible criteria
    id: search-the-ansname-registry-with-flexible-criteria
    contents:
  * content: >
    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.
    heading: search-the-ansname-registry-with-flexible-criteria

***

## 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:

- object
  - `agents` (required): array — List of matching agents
      - items:
          - `agentDescription`: string — Description of the agent
          - `agentHost` (required): string — The agent's hosting domain
          - `agentDisplayName` (required): string — Human-readable display name for the agent
          - `ansName` (required): string — Full ANS name of the agent in format ans://{version}.{agentHost}
          - `agentId` (required): string — Unique identifier of the agent
          - `endpoints` (required): array — Array of agent endpoints with protocol-specific configuration
              - items:
                  - `agentUrl` (required): string <uri> — The URL where the agent is hosted and accepts requests
                  - `metaDataUrl`: string <uri> — URL for agent metadata (optional)
                  - `documentationUrl`: string <uri> — URL for agent documentation (optional)
                  - `protocol` (required): string — Communication protocol for this endpoint
                    - enum: "A2A", "MCP", "HTTP-API"
                  - `functions`: array — Array of functions provided by this endpoint. The meaning varies by protocol: for MCP these are tools (e.g., 'domain_suggest', 'file_search'), for A2A these are skills (e.g., 'translate_document', 'analyze_sentiment'), and for HTTP-API these are routes (e.g., 'GET /domains', 'POST /orders'). (optional)
                      - items:
                          - `id` (required): string — Unique identifier for the function
                          - `name` (required): string — Human-readable name for the function
                          - `tags`: array — Tags for categorizing and discovering functions (max 5 tags, each up to 20 characters)
                              - items:
                  - `transports`: array — Supported transport mechanisms for the protocol (optional)
                      - items:
                          - enum: "STREAMABLE-HTTP", "SSE", "JSON-RPC", "GRPC", "REST", "HTTP"
          - `links` (required): array — HATEOAS links for related operations
              - items:
                  - `href` (required): string <uri> — Link URL
                  - `rel` (required): string — Link relation type
          - `registrationTimestamp`: string <date-time> — When the agent was registered
          - `ttl`: integer <int32> — Time-to-live in seconds
          - `version` (required): string — Agent version
  - `hasMore` (required): boolean — Whether there are more results available
  - `limit` (required): integer <int32> — Maximum number of results requested
  - `offset` (required): integer <int32> — Number of results skipped for pagination
  - `returnedCount` (required): integer <int32> — Number of agents returned in this response
  - `searchCriteria`: object
      - `agentHost`: string — Agent host domain used for search
      - `agentDisplayName`: string — Agent display name used for search
      - `protocol`: string — Communication Protocol used by agents
        - enum: "A2A", "MCP", "HTTP-API"
      - `version`: string — Version used for search
  - `totalCount` (required): integer <int32> — Total number of matching agents (across all pages)

**401** — Authentication failed

Content-Type: `application/json`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**403** — Authorization failed

Content-Type: `application/json`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

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

Content-Type: `application/json`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"

**500** — Internal server error

Content-Type: `application/json`

Schema:

- object
  - `code` (required): string — Application-specific error code for client-side error handling
  - `details`: object
  - `message` (required): string
  - `status` (required): string
    - enum: "ERROR"