---
id: agent-list
title: "List agents"
description: "Lists agents within an organization."
sidebar_label: "List agents"
hide_title: true
hide_table_of_contents: true
api: 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
sidebar_class_name: "get api-method"
info_path: docs/api/control-plane
custom_edit_url: null
---

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List agents"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/controlplane/agent"}
  context={"endpoint"}
>
  
</MethodEndpoint>



Lists agents within an organization.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"in":"query","name":"organization_id","schema":{"type":"integer"},"description":"The ID of the organization.","example":1234},{"in":"query","name":"account_id","schema":{"type":"integer"},"description":"The ID of the account.","example":2345},{"in":"query","name":"nrn","schema":{"type":"string"},"description":"Filter agents by a specific NRN.","example":"organization=1:account=2"},{"in":"query","name":"status","schema":{"type":"string","enum":["active","inactive"]},"required":false,"description":"Status of the scope."},{"in":"query","name":"tags","schema":{"type":"string"},"description":"Object containing key-value pairs representing tags to be matched for applying the configuration.","example":"environment:production,service:api"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The list of agents matching the query.","content":{"application/json":{"schema":{"type":"object","required":["paging","results"],"properties":{"paging":{"type":"object","required":["offset","limit"],"properties":{"offset":{"type":"integer","minimum":0,"description":"The starting point for pagination. Defaults to 0 if not provided.","example":0},"limit":{"type":"integer","maximum":200,"description":"The maximum number of results to return per page. The maximum allowed value is 200.","example":200}}},"results":{"type":"array","items":{"type":"object","required":["id","name","last_heartbeat","runtime","version","tags","status","created_at"],"properties":{"id":{"type":"string","description":"A system-wide unique ID for the agent.","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479"},"name":{"type":"string","description":"The name of the agent.","nullable":true,"example":"my-agent-name"},"nrns":{"type":"array","description":"List of NRNs the agent is authorized to operate on, derived from the API key permissions.","items":{"type":"string"},"example":["organization=1:account=2","organization=1:account=2:namespace=3"]},"last_heartbeat":{"type":"string","format":"date-time","description":"The ISO-8601 UTC timestamp of the last heartbeat from the agent.","example":"2021-01-02T00:00:00Z"},"runtime":{"type":"string","description":"The runtime the agent runs on, for example, `k8s` or `host`.","example":"k8s"},"version":{"type":"string","description":"The version of the agent.","example":"1.0.0"},"tags":{"type":"object","description":"Object containing key-value pairs representing tags to be matched for applying the configuration.","example":"environment:production,node_name:node-1"},"status":{"type":"string","description":"The status of the agent.","enum":["active"],"example":"active"},"created_at":{"type":"string","format":"date-time","description":"The ISO-8601 UTC timestamp of when the agent was created.","example":"2021-01-02T00:00:00Z"},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"The ISO-8601 UTC timestamp of when the agent was last updated.","example":"2021-01-02T00:00:00Z"},"capabilities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A system-wide unique ID for the capability.","example":"commandexecutor1"},"tags":{"type":"object","description":"Object containing key-value pairs representing tags to be matched for applying the capability.","example":"environment:production,node_name:node-1"},"status":{"type":"string","description":"The status of the capability.","enum":["active"],"example":"active"},"version":{"type":"string","description":"The version of the capability.","example":"1.0.0"},"configuration_id":{"type":"string","description":"The ID of the configuration.","example":"config1"},"desired_configuration_id":{"type":"string","description":"The ID of the desired configuration.","example":"desired_config1"},"is_default_configuration":{"type":"boolean","description":"Defines whether this capability is the default configuration.","enum":[true,false],"example":true},"current_configuration_expires_at":{"type":"string","format":"date-time","nullable":true,"description":"The expiration date of the current configuration.","example":"2024-07-12T15:00:00Z"},"provider":{"type":"string","description":"The provider of the capability.","example":"commandexecutor1"},"category":{"type":"string","description":"The category of the capability.","example":"executor1"},"created_at":{"type":"string","format":"date-time","description":"The ISO-8601 UTC timestamp of when the capability was created.","example":"2021-01-02T00:00:00Z"},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"The ISO-8601 UTC timestamp of when the capability was last updated.","example":"2021-01-02T00:00:00Z"}},"title":"capability"}}},"title":"agent"}}},"title":"agentListResponse"}}}},"4XX":{"description":"Client error responses due to invalid input or missing parameters.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","message"],"properties":{"statusCode":{"type":"integer","description":"HTTP status code representing the specific client error (e.g., 400, 401, 403, 404).","example":400},"code":{"type":"string","description":"A machine-readable error code that categorizes the server failure.","example":"bad_request"},"error":{"type":"string","description":"A brief, human-readable description of the error type (e.g., \"Bad Request\", \"Unauthorized\").","example":"Bad Request"},"message":{"type":"string","description":"Additional details about the error.","example":"The request was malformed or contained invalid parameters."}}}}}},"5XX":{"description":"Server error responses indicating an issue on the API side.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","message"],"properties":{"statusCode":{"type":"integer","description":"HTTP status code representing the specific server error (e.g., 500, 502, 503).","example":500},"code":{"type":"string","description":"A machine-readable error code that categorizes the server failure.","example":"internal_server_error"},"error":{"type":"string","description":"A brief, human-readable description of the error type (e.g., \"Internal Server Error\", \"Service Unavailable\").","example":"Internal Server Error"},"message":{"type":"string","description":"Additional details about the error.","example":"An unexpected error occurred. Please try again later."}}}}}}}}
>
  
</StatusCodes>