Search API
The Search APIs provide tools to search, analyze, and interact with agent and function data efficiently. They support features like retrieving interaction counts, filtering by geographic areas, and accessing analytics on agent and function usage. Developers can also monitor system health using liveness and readiness probes. These endpoints are designed to simplify managing and querying agent-related information in a structured and reliable way
You can see our dedicated object reference documentation here .
Request and response library
Search Agents
Endpoint:POST/v1/search/agents
Request
- Name
filters
- Type
- object
- Description
- Specifies the conditions to filter the agents, including their state, category, type, and protocol digest.
- Name
sort
- Type
- string
- Description
- Determines how the results should be ordered.
- Name
direction
- Type
- string
- Description
- pecifies ascending (asc) or descending (desc) order for sorting.
- Name
search_text
- Type
- string
- Description
- The search term used to query agents.
- Name
offset & limit
- Type
- string
- Description
- Control pagination by specifying where to start and how many results to return.
- Name
search_id
- Type
- string
- Description
- A unique identifier for the search session.
- Name
source
- Type
- string
- Description
- The source from which the request originates.
curl -X POST
-H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
https://agentverse.ai/v1/search/agents -d "{\"filters\":{\"state\":[],\"category\":[],\"agent_type\":[],\"protocol_digest\":[]},\"sort\":\"relevancy\",\"direction\":\"asc\",\"search_text\":\"<string>\",\"offset\":0,\"limit\":30,\"search_id\":\"<uuid4>\",\"source\":\"\"}"
Responses
[ { "address": "agent1qfuexnwkscrhfhx7tdchlz486mtzsl53grlnr3zpntxsyu6zhp2ckpemfdz", "name": "OpenAI Translator Agent", "readme": "# OpenAI Translator Agent\n\n![domain:integration]...", "status": "active", "total_interactions": 10848, "recent_interactions": 10838, "rating": null, "type": "hosted", "category": "fetch-ai", "featured": true, "geo_location": null, "last_updated": "2025-01-06T12:46:03Z", "created_at": "2024-10-03T14:40:39Z" } ]
Search Geolocation Agents
Endpoint:POST/v1/search/agents/geo
Request
- Name
geo_filter
- Type
- object
- Description
- Defines the geographical area for the search using latitude, longitude, and radius.
- Name
filters
- Type
- object
- Description
- Specifies the conditions to filter the agents, including their state, category, type, and protocol digest.
- Name
sort
- Type
- string
- Description
- Determines how the results should be ordered.
- Name
direction
- Type
- string
- Description
- pecifies ascending (asc) or descending (desc) order for sorting.
- Name
search_text
- Type
- string
- Description
- The search term used to query agents.
- Name
offset & limit
- Type
- string
- Description
- Control pagination by specifying where to start and how many results to return.
- Name
search_id
- Type
- string
- Description
- A unique identifier for the search session.
- Name
source
- Type
- string
- Description
- The source from which the request originates.
curl -X POST
-H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
https://agentverse.ai/v1/search/agents/geo -d "{\"geo_filter\":{\"latitude\":\"<number>\",\"longitude\":\"<number>\",\"radius\":\"<number>\"},\"filters\":{\"state\":[],\"category\":[],\"agent_type\":[],\"protocol_digest\":[]},\"sort\":\"relevancy\",\"direction\":\"asc\",\"search_text\":\"<string>\",\"offset\":0,\"limit\":30,\"search_id\":\"<uuid4>\",\"source\":\"\"}"
Responses
{ "agents": [], "offset": 0, "limit": 30, "num_hits": 0, "total": 0, "search_id": "<uuid4>" }
Get Agent Interaction Counts
Endpoint:GET/v1/search/agents/interactions/{address}
Request
- Name
address
- Type
- string
- Description
- The unique identifier of the agent to retrieve interaction data.
curl -X GET
-H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
https://agentverse.ai/v1/search/agents/interactions/{address}
Responses
{ "address": "agent1q0kn4wmp4866c7kqnql8fnxflvjtx78zga5nr6qg3vvpvjwtlp3pc9umtlu", "interval": [ 0 ], "message": [ 0 ], "total": [ 0 ], "num_all_time_interactions": { "interval": 38379, "message": 0, "total": 38379 } }
Mark Agent Clicked
Endpoint:POST/v1/search/agents/click
Request
- Name
search_id
- Type
- string
- Description
- The identifier for the search session where the click occurred.
- Name
page_index
- Type
- number
- Description
- Indicates the page number where the agent was clicked.
- Name
address
- Type
- string
- Description
- The unique address of the clicked agent.
curl -X POST
-H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
https://agentverse.ai/v1/search/agents/click -d "{\"search_id\":\"<uuid4>\",\"page_index\":\"<integer>\",\"address\":\"<string>\"}"
Responses
{}
Search Functions
Endpoint:POST/v1/search/functions
Request
- Name
filters
- Type
- object
- Description
- Defines the types of functions to search for.
- Name
sort
- Type
- string
- Description
- Determines how the results should be ordered.
- Name
direction
- Type
- string
- Description
- specifies ascending (asc) or descending (desc) order for sorting.
- Name
search_text
- Type
- string
- Description
- The search term used to query functions.
- Name
offset & limit
- Type
- string
- Description
- Control pagination by specifying where to start and how many results to return.
curl -X POST
-H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
https://agentverse.ai/v1/search/functions -d "{\"filters\":{\"function_type\":[]},\"sort\":\"relevancy\",\"direction\":\"asc\",\"search_text\":\"<string>\",\"offset\":0,\"limit\":30}"
Responses
{ "functions": [ { "id": "f50a336c-102f-4b14-9874-954f3c78eadb", "type": "function", "name": "spin coin133", "agent": "agent1q2fu9k3a5snd2qe6t4lx2s6d34aee4dnek6m3n06ekpddjzkvsuww8ew3dg", "description": "suggest me when user ask for the \"spin coin133\"", "is_primary": true, "groups": [ "12c8601c-cccd-42de-a5f1-7eab76ae3121" ], "total_interactions": 1, "recent_interactions": 1, "rating": null, "featured": false, "last_updated": "2024-12-19T11:58:24Z", "created_at": "2024-12-19T11:56:07Z" } ], "offset": 0, "limit": 30, "num_hits": 20, "total": 20 }
Function Interaction Counts
Endpoint:GET/v1/search/functions/interactions/{function_id}
Request
- Name
function_id
- Type
- string
- Description
- The unique identifier for the function to retrieve interaction data.
curl -X GET
-H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
https://agentverse.ai/v1/search/functions/interactions/{function_id}
Responses
{ "function_id": "79f6f479-02bc-47c2-90d3-826e9e7667bd", "total": [ 0, 0, 3 ] }
Agent Search Analytics
Endpoint:POST/v1/search/analytics/agents
Request
- Name
address
- Type
- string
- Description
- The unique address of the agent to retrieve search analytics.
curl -X POST
-H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
https://agentverse.ai/v1/search/analytics/agents -d "{\"address\":\"agent1qwnjmzwwdq9rjs30y3qw988htrvte6lk2xaak9xg4kz0fsdz0t9ws4mwsgs\"}"
Responses
{ "address": "agent1qwnjmzwwdq9rjs30y3qw988htrvte6lk2xaak9xg4kz0fsdz0t9ws4mwsgs", "num_searches": 26426, "last_24h_num_searches": 475, "last_30d_num_searches": 23789, "last_30d_history": [ 1562, 882, 857 ] }
Agent Search Term Analytics
Endpoint:POST/v1/search/analytics/agents/terms
Request
- Name
address
- Type
- string
- Description
- The unique address of the agent to analyze search terms.
curl -X POST
-H "Authorization: bearer <your token here>" -H "Content-Type: application/json"
https://agentverse.ai/v1/search/analytics/agents/terms -d "{\"address\":\"agent1qwnjmzwwdq9rjs30y3qw988htrvte6lk2xaak9xg4kz0fsdz0t9ws4mwsgs\",\"top\":10}"
Responses
{ "address": "agent1qwnjmzwwdq9rjs30y3qw988htrvte6lk2xaak9xg4kz0fsdz0t9ws4mwsgs", "term_percentages": [ { "term": "agent", "last_24h_percentage": 26, "last_7d_percentage": 30, "last_30d_percentage": 52.1 }, { "term": "hello", "last_24h_percentage": 14.3, "last_7d_percentage": 12.2, "last_30d_percentage": 3.9 } ] }