---
id: agent-read
title: "Read an agent"
description: "Retrieve a specific agent by its ID."
sidebar_label: "Read an agent"
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={"Read an agent"}
>
</Heading>

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



Retrieve a specific agent by its ID.

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

<ParamsDetails
  parameters={[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The unique ID of the agent.","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479"}]}
>
  
</ParamsDetails>

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

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"The operation was successful.","content":{"application/json":{"schema":{"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"}}}},"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>