How to Use the Agent Collection API Endpoint

APIs & Developer Support
1

Hello, API enthusiasts! Today, we’re diving into the Agent Collection API endpoint. With this powerful API, you can fetch a collection of agents, filter, order, and paginate the result set. In this post, we’ll walk you through examples of how to use it and discuss some useful use-cases you can implement with it.

Endpoint:
GET /agents

Base URL:
https://[HOSTNAME]

Authorization:
Bearer Token

How to Use the Agent Collection API Endpoint

Let’s explore some examples on how to interact with the API endpoint.

1. Fetching All Agents

To fetch all agents without any filters or pagination, use the following request:

GET https://[HOSTNAME]/agents?type=beta
Authorization: Bearer <Your-API-Token>

2. Fetching Agents with Filters

The API provides various filter options to fetch agents based on different criteria, such as name, category, agent class, active status, and more. Here’s an example of fetching agents with specific filters:

GET https://[HOSTNAME]/agents?type=beta&filter[name]=example name&filter[category]=network_agent&filter[active]=true
Authorization: Bearer <Your-API-Token>

This request will fetch agents with a name containing “example name,” belonging to the “network_agent” category, and are currently active.

3. Paginating and Sorting Agents

To paginate and sort the agents, use the “page[offset],” “page[limit],” “order[attributes],” and “order[direction]” parameters. The following example fetches agents sorted by name in descending order, with a limit of 10 agents per page and the offset set to the second page:

GET https://[HOSTNAME]/agents?type=beta&page[offset]=2&page[limit]=10&order[attributes]=name&order[direction]=desc
Authorization: Bearer <Your-API-Token>

Use-Cases

Here are some useful use-cases you can implement using the Agent Collection API endpoint:

  1. Agent Monitoring Dashboard: Build a monitoring dashboard to display agent status, active incidents, and alert counts. You can use filters like filter[active], filter[warning_alerts][min],filter[warning_alerts][max], filter[critical_alerts][min],filter[critical_alerts][max] to fetch specific agent data.

  2. Resource Allocation and Planning: Analyze agent data to optimize resource allocation, such as determining if any agents are reaching their target test limit or scheduled test limit.

  3. Network Infrastructure Analysis: Investigate network interfaces, access points, and agent types to gain insights into your network infrastructure, identify bottlenecks, and improve overall network performance.

  4. Agent Inventory Management: Keep track of agent categories, classes, software versions, and other attributes to manage agent inventory and plan future updates or expansions.

Don’t forget to replace [HOSTNAME] with your actual API hostname and <Your-API-Token> with your valid API token.

That’s it! Now you have a better understanding of how to interact with the Agent Collection API endpoint and some useful use-cases to implement. Explore the API further, and feel free to share your experiences or ask questions in the community! Happy coding!

2

We now have a new endpoint that exports the agent data (hardcoded columns) into CSV format directly.

All you have to do is use the endpoint described above and add a .csv at the end:

https://{MY_HOST}/agents.csv?

The output looks like this:

id,name,default_name,category,agent_class,active,software_version,logged_in_user,wired_mac_address,wired_ip_address,wired_gateway,wired_dns_server1,wired_dns_server2,external_ip_address,wireless_mac_address,wireless_ip_address,wireless_gateway,wireless_dns_server1,wireless_dns_server2,isp_name,isp_asn,last_seen_at
140,dummy wired,[1.2.3.41-00:41],network_agent,faste,true,12.0.1,,00:00:00:00:00:41,1.2.3.41,192.168.0.1,1.1.1.1,,108.32.61.173,,,,,,Verizon Business,AS701,2024-03-25 23:14:38 -0400
139,dummy WiFi,[1.2.3.43-00:43],network_agent,wireless,true,12.0.1,,00:00:00:00:00:43,1.2.3.43,192.168.0.1,1.1.1.1,,108.32.61.173,00:00:00:00:01:43,10.2.3.43,192.168.0.1,1.1.1.1,,Verizon Business,AS701,2024-03-25 23:14:43 -0400