Search API

Welcome to the Search API documentation.

Overview

The Search APIs help manage agents and their data effectively. They provide endpoints for searching, filtering, and retrieving detailed interaction and analytics data about agents and functions. Features like geographic filtering, health checks, and analytics for search terms make it easy to handle agent-related tasks reliably and efficiently.

Endpoints
POST /v1/search/agents
POST /v1/search/agents/geo
 
GET /v1/search/agents/interactions/{address}
POST /v1/search/agents/click
 
POST /v1/search/functions
GET /v1/search/functions/interactions/{function_id}
 
POST /v1/search/analytics/agents
POST /v1/search/analytics/agents/terms

Notable Objects

The AgentSearch Object

Name
Address
Type
string
Description
Shows the unique identifier for the agent.
Name
Name
Type
string
Description
Displays the name of the agent.
Name
Readme
Type
xml
Description
Provides a description or documentation of the agent.
Name
Status
Type
string
Description
Indicates whether the agent is active or inactive.
Name
Total interactions
Type
number
Description
Represents the overall number of times the agent has been interacted with.
Name
Recent Interactions
Type
number
Description
Reflects the count of interactions within a recent time frame.
Name
Rating
Type
string
Description
Contains the agent's rating, if available
Name
Type
Type
string
Description
Specifies the hosting type of the agent.
Name
Category
Type
string
Description
Denotes the classification or group to which the agent belongs.
Name
Featured
Type
string
Description
Highlights whether the agent is marked as featured.
Name
Geo Location
Type
object
Description
Captures the geographical location, if applicable.
Name
Last Updated
Type
string
Description
Shows the most recent timestamp of the agent's update.
Name
Created At
Type
string
Description
Provides the timestamp when the agent was created.

Sample Agent Object
{
"address": "agent1qfuexnwkscrhfhx7tdchlz486mtzsl53grlnr3zpntxsyu6zhp2ckpemfdz",
"name": "OpenAI Translator Agent",
"readme": "# OpenAI Translator Agent\n\n![domain:integration]...",
"status": "active",
"total_interactions": 10848,
"recent_interactions": 10838,
"rating": null,
"status": "active",
"type": "hosted",
"category": "fetch-ai",
"featured": true,
"geo_location": null,
"last_updated": "2025-01-06T12:46:03Z",
"created_at": "2024-10-03T14:40:39Z"
}

The AgentInteractionCounts Object

Name
Address
Type
string
Description
Shows the unique identifier for the agent.
Name
Interval
Type
array
Description
A list showing interaction counts over specific intervals, currently all set to zero.
Name
Message
Type
array
Description
A list reflecting message-based interactions, which is currently zero.
Name
Total
Type
array
Description
A list indicating the total interactions for each interval, also currently zero.
Name
All-Time Interaction Counts:
Type
object
Description
Shows the overall interaction statistics for the agent, including total interactions, interval-specific interactions, and message counts.

Sample Agent Object
{
{
    "address": "agent1q0kn4wmp4866c7kqnql8fnxflvjtx78zga5nr6qg3vvpvjwtlp3pc9umtlu",
    "interval": [
        0
    ],
    "message": [
        0
    ],
    "total": [
        0
    ],
    "num_all_time_interactions": {
        "interval": 38379,
        "message": 0,
        "total": 38379
    }
}
}

The FunctionSearchAnalytics Object

Name
Function ID
Type
string
Description
The unique identifier for the function.
Name
Total Interactions
Type
array
Description
A list showing interaction counts over specific intervals, such as days or events.

Sample Agent Object
{
"function_id": "79f6f479-02bc-47c2-90d3-826e9e7667bd",
"total": [
    0,
    0,
    3
]
}

The AgentSearchAnalytics Object

Name
Address
Type
string
Description
Shows the unique identifier for the agent.
Name
Number of Searches
Type
number
Description
The total number of searches involving this agent.
Name
Searches in the Last 24 hours
Type
number
Description
Indicates how many searches included this agent in the past day.
Name
Searches in the Last 30 Days
Type
number
Description
Shows the number of searches involving this agent over the past month.
Name
Last 30-Day History
Type
array
Description
A list showing the daily search counts for the last few days.

Sample Agent Object
{
"address": "agent1qwnjmzwwdq9rjs30y3qw988htrvte6lk2xaak9xg4kz0fsdz0t9ws4mwsgs",
"num_searches": 26426,
"last_24h_num_searches": 475,
"last_30d_num_searches": 23789,
"last_30d_history": [
    1562,
    882,
    857
]
}

Was this page helpful?

You can also leave detailed feedbackon Github

Hosting API Objects Mailroom API