How to bulk-remove agents from the dashboard using the API

Hello NetBeez community! I am a software engineer at NetBeez and I am going to show some simple steps to remove agents from the dashboard in bulk using the API. This is useful when we need to remove a large number of agents from the dashboard. For example, when we want to remove all agents that have not been active for a long time. Let’s get started!

Step 1: Get the list of agents to remove

First, we need to get the list of agents that we want to remove. We can do this by using the Agents API. Check out this other community post about How to Use the Agent Collection API Endpoint for more details. The Agents API supports different types of filters. For example, we can filter by agent group, agent type, or ISP name. Depending on what set of agents we need to remove, we can use different combinations of filters.

  1. Get all agents that haven’t been active for some time

For example, if we want to get all agents that have not been active for a long time, we can use the following filters:

GET https://{{HOSTNAME}}/agents?type=beta&filter[active]=false&filter[active_ts][operator]=<&filter[active_ts][value]=1687708893000
Authorization: Bearer <Your-API-Token>

The filter filter[active]=false narrows the query down to agents that aren’t currently active.

The filter filter[active_ts][operator]=< is restricting the query to agents that have a last active timestamp older than the timestamp specified in the next filter filter[active_ts][value]. For example, if we wanted to get all agents that have not been active for the last 30 days, you would find today’s timestamp, e.g. 1690300893000 (July 25, 2023 4:01:33 PM) and subtract 30 days (30 * 24 * 60 * 60 * 1,000 = 2,592,000,000 milliseconds) from it. The result would be 1687708893000 (June 25, 2023 4:01:33 PM). Then, we would use this timestamp in the filter filter[active_ts][value]=1687708893000.

  1. Get all agents that belong to a specific agent group and are currently offline (not active)

First we need to find the ID of the agent group we want to filter by. We can do this by using the Agent Groups API. Then, we can run an Agents API query with following filters:

GET https://{{HOSTNAME}}/agents?type=beta&filter[active]=false&filter[agent_groups]=3
Authorization: Bearer <Your-API-Token>

The agent_groups filter accepts a comma-separated list of agent group IDs as well.

Step 2: Remove the agents

Now that we have the list of agents that we want to remove, we can use the DELETE operation of the Agents API to actually remove them. For every Agent ID retrieved in the previous section, we can send a DELETE request to the following endpoint:

DELETE https://{{HOSTNAME}}/agents/:id?type=beta
Authorization: Bearer <Your-API-Token>

where :id is the ID of the agent that we want to remove.

How to automate the process using a script

If we have many agents to remove we will want to automate the steps. Here is an example script in Python that automates the previously described process. The script has three variables: the hostname of the NetBeez dashboard, the API token, and the number of days that an agent has not been active. Then, it retrieves the list of agents that have not been active for the specified number of days and removes them from the dashboard.

import requests
import datetime

# Replace these with your actual values
API_HOSTNAME = "your_api_hostname"
API_TOKEN = "your_api_token"

# Timestamp in milliseconds of {NUMBER_OF_DAYS} days before right now
LAST_ACTIVE_TS = int(( - datetime.timedelta(days=NUMBER_OF_DAYS)).timestamp() * 1000)  

def get_non_active_agents():
    url = f"https://{API_HOSTNAME}/agents?type=beta&filter[active]=false&filter[active_ts][operator]=<&filter[active_ts][value]={LAST_ACTIVE_TS}"
    headers = {"Authorization": f"Bearer {API_TOKEN}"}

    response = requests.get(url, headers=headers)
    response_data = response.json()

    if response.status_code == 200:
        return response_data.get("data", [])
        print("Error getting non-active agents:")
        return []

def delete_agent(agent_id):
    url = f"https://{API_HOSTNAME}/agents/{agent_id}?type=beta"
    headers = {"Authorization": f"Bearer {API_TOKEN}"}

    response = requests.delete(url, headers=headers)

    if response.status_code == 204:
        print(f"Agent with ID {agent_id} deleted successfully.")
        print(f"Error deleting agent with ID {agent_id}: {response.text}")

if __name__ == "__main__":
    non_active_agents = get_non_active_agents()

    if not non_active_agents:
        print(f"No non-active agents found with active_ts < {LAST_ACTIVE_TS}.")
        print(f"Found {len(non_active_agents)} non-active agents:")
        for agent in non_active_agents:
            agent_id = agent.get("id")
            if agent_id:

By following the described steps or running the provided script (with the corresponding adjustments) we will be able to easily remove a set of agents from the NetBeez dashboard according to some criteria by using the relevant API filters.