--- title: "Get agent" method: GET path: "/v1/projects/{project_id}/agents/{agent_name}" tags: ["agents"] --- # Get agent `GET /v1/projects/{project_id}/agents/{agent_name}` ## Request - Base URL: `https://api.connic.co` - URL: `https://api.connic.co/v1/projects/{project_id}/agents/{agent_name}` - Auth: HTTP bearer Returns the agent's configuration from the active deployment (null when the active deployment does not contain it), run statistics, token usage and cost, linked connectors, and average scores of its judges in the given environment. Statistics and judge averages cover runs queued in the selected window (the last 30 days by default), narrowed by the run filters. Required permission: `agents.view`. ## Path parameters - `project_id` string, uuid, required - `agent_name` string, required ## Query parameters - `environment_id` string, uuid, required: Target environment UUID - `time_range` '24h' | '7d' | '30d' | '90d' | 'today' | 'this_month' | 'last_month' | 'this_year' | 'all', nullable: Preset statistics window ending now, a calendar period in UTC, or `all` for no time limit. Ignored when `start_date` is set. - `start_date` string, date-time, nullable: Custom statistics window start; overrides `time_range`. - `end_date` string, date-time, nullable: Custom statistics window end; used only with `start_date`, which is open-ended without it. - `deployment_id` string, uuid, nullable: Only include runs executed by this deployment. - `status_filter` RunStatus[], nullable: Restrict stats to statuses - `guardrail_outcome` string[], nullable: Restrict stats to guardrail outcomes - `test_name` string[], nullable: A/B test variant names; use __base__ for runs without a variant - `exclude_test_runs` boolean: Exclude runs with a test name - `search` string, nullable: Run search text or filter expression, as in `GET /runs`. - `convert_costs_to` 'EUR' | 'USD', nullable: Convert token costs to EUR or USD at the daily ECB reference rate of each model call ## Response `200` Successful Response - PublicAgentDetailsResponse - `agent` PublicAgentIdentityResponse, required - `name` string, required - `project_id` string, uuid, required: Project the agent belongs to. - `is_active` boolean, required: Whether the agent is part of the environment's active deployment. - `config` PublicAgentConfigResponse, required: Agent configuration from the active deployment. Fields mirror the agent's YAML definition. - `type` string, required: `llm`, `sequential` (runs other agents in order) or `tool` (runs one tool directly). - `source_path` string, nullable, required: Path of the agent's YAML file in your code. - `description` string, nullable, required: Description from the agent definition. - `model` string, nullable, required: Model the agent uses. Null for sequential and tool agents. - `fallback_model` string, nullable, required: Model used after a failed request to the primary model. Null when not set. - `temperature` number, nullable, required: Sampling temperature, from 0 to 2. - `max_concurrent_runs` integer, required: Maximum runs of this agent that execute at the same time. Defaults to 1. - `max_iterations` integer, nullable, required: Maximum model calls per run. - `timeout` number, nullable, required: Maximum run time in seconds, capped by the plan's limit. Null when not set. - `reasoning_effort` string, nullable, required: Reasoning effort: `auto`, `off`, `minimal`, `low`, `medium`, `high` or `xhigh`. Null when not set. - `reasoning_budget` integer, nullable, required: Deprecated reasoning token budget for legacy models. Null when not set. - `output_schema` string, nullable, required: Name of the JSON schema file in `schemas/` (without `.json`) that structures the agent's output. Null when the agent has none. - `agents` union[], nullable, required: Agents a sequential agent runs, in order. Empty for other types. - union - string - object - `tool_name` string, nullable, required: Tool a tool agent executes, as a module path under `tools/`. Null for other types. - `retry_options` object, nullable, required: Retry settings passed through from the agent definition: `attempts`, `initial_delay`, `max_delay` and `rerun_middleware`. - `session` object, nullable, required: Persistent session settings passed through from the agent definition. Null when sessions are off. - `concurrency` union, required: Key-based concurrency settings (`key`, `on_conflict`) passed through from the agent definition. Null when not set. - object - integer - `tools` union[], nullable, required: Tools the agent can call, as listed in the agent definition. - union - string - object - `discoverable_tools` union[], nullable, required: Tools the agent finds on demand through tool search instead of loading them upfront. - union - string - object - `mcp_servers` union[], nullable, required: MCP servers the agent connects to, passed through from the agent definition (`name`, `url`, `discoverable`, `bridge`, `oauth_app`). - union - string - object - `guardrails` union, required: Input and output guardrail rules with their `type` and `mode`. Null when none are configured. - union[] - union - string - object - object - `database` object, nullable, required: Database access settings (`collections`, `prevent_delete`, `prevent_write`). Null means unrestricted access. - `retrieval` object, nullable, required: Retrieval access settings (`namespaces`, `prevent_delete`, `prevent_write`). Null means unrestricted access. - `stats` PublicAgentStatsResponse, required - `total_runs` integer, required: Runs matching the filters. - `active_runs` integer, required: Matching runs currently executing. - `queued_runs` integer, required: Matching runs waiting in the queue. - `failed_runs` integer, required: Matching runs that failed. - `total_duration_sec` number, required: Sum of run durations in seconds, from start to end. - `avg_duration_sec` number, required: Mean run duration in seconds. 0 when no run has finished. - `p50_duration_sec` number, required: Median run duration in seconds. 0 when no run has finished. - `p95_duration_sec` number, required: 95th percentile run duration in seconds. 0 when no run has finished. - `token_usage` PublicTokenUsageResponse, required: Token counts summed over model calls. - `input_tokens` integer, required: Prompt tokens sent to the model, including cached tokens. - `output_tokens` integer, required: Tokens the model generated, excluding thinking tokens. - `cached_input_tokens` integer, required: Part of `input_tokens` read from the provider's prompt cache. - `thinking_tokens` integer, required: Reasoning tokens the model generated. - `total_tokens` integer, required: Input, output and thinking tokens combined. - `audio_input_tokens` integer: Part of `input_tokens` that was audio. - `audio_output_tokens` integer: Part of `output_tokens` that was audio. - `audio_cached_input_tokens` integer: Part of `cached_input_tokens` that was audio. - `audio_thinking_tokens` integer: Part of `thinking_tokens` that was audio. - `audio_usage_missing` boolean: True when at least one model call did not report its audio breakdown, so audio counts may be too low. - `agent_token_usage` PublicTokenUsageResponse, required: Token counts summed over model calls. - `input_tokens` integer, required: Prompt tokens sent to the model, including cached tokens. - `output_tokens` integer, required: Tokens the model generated, excluding thinking tokens. - `cached_input_tokens` integer, required: Part of `input_tokens` read from the provider's prompt cache. - `thinking_tokens` integer, required: Reasoning tokens the model generated. - `total_tokens` integer, required: Input, output and thinking tokens combined. - `audio_input_tokens` integer: Part of `input_tokens` that was audio. - `audio_output_tokens` integer: Part of `output_tokens` that was audio. - `audio_cached_input_tokens` integer: Part of `cached_input_tokens` that was audio. - `audio_thinking_tokens` integer: Part of `thinking_tokens` that was audio. - `audio_usage_missing` boolean: True when at least one model call did not report its audio breakdown, so audio counts may be too low. - `judge_token_usage` PublicTokenUsageResponse, required: Token counts summed over model calls. - `input_tokens` integer, required: Prompt tokens sent to the model, including cached tokens. - `output_tokens` integer, required: Tokens the model generated, excluding thinking tokens. - `cached_input_tokens` integer, required: Part of `input_tokens` read from the provider's prompt cache. - `thinking_tokens` integer, required: Reasoning tokens the model generated. - `total_tokens` integer, required: Input, output and thinking tokens combined. - `audio_input_tokens` integer: Part of `input_tokens` that was audio. - `audio_output_tokens` integer: Part of `output_tokens` that was audio. - `audio_cached_input_tokens` integer: Part of `cached_input_tokens` that was audio. - `audio_thinking_tokens` integer: Part of `thinking_tokens` that was audio. - `audio_usage_missing` boolean: True when at least one model call did not report its audio breakdown, so audio counts may be too low. - `runs_with_tokens` integer, required: Runs with at least one recorded model call. - `token_cost` PublicTokenCostResponse, required: Token cost in each model's pricing currency, or in one currency when `convert_costs_to` is set. - `amounts` object, required: Total cost keyed by currency code (`EUR` or `USD`), as a decimal string with 12 decimal places. Only currencies with a nonzero amount are included. - `breakdown` object, required: Cost split by token type and by agent versus judge, keyed by currency code. - `coverage` PublicTokenCostCoverageResponse, required: How many model calls could be priced. - `complete` boolean, required: True when every model call could be priced. - `call_count` integer, required: Model calls covered by the report. - `priced_call_count` integer, required: Calls included in the cost amounts. - `unpriced_call_count` integer, required: Calls without a known price or without reported token usage. They are left out of the amounts. - `unpriced_models` string[], required: Models of the unpriced calls. - `converted_to` string, nullable: Currency the amounts were converted to at the daily ECB reference rate of each call. Present only when `convert_costs_to` is set. - `native_amounts` object, nullable: Totals in each model's pricing currency before conversion, as decimal strings keyed by currency code. Present only when `convert_costs_to` is set. - `token_cost_statistics` object, required: Cost per run keyed by currency code, including judge costs, over runs whose calls could all be priced. - `avg_tokens_per_run` number, required: Mean agent tokens per run, over runs with recorded model calls. - `p50_tokens_per_run` number, required: Median agent tokens per run, over runs with recorded model calls. - `p95_tokens_per_run` number, required: 95th percentile agent tokens per run, over runs with recorded model calls. - `connectors` PublicAgentConnectorResponse[], required: Connectors linked to the agent in this environment. - `id` string, uuid, required - `name` string, required - `type` string, required: Connector type, such as `http` or `cron`. - `mode` string, required: `inbound`, `outbound` or `sync`. - `enabled` boolean, required: False when the connector is paused. - `link_id` string, uuid, nullable: ID of the link between this agent and the connector. - `link_config` object, nullable: Settings of that link, as returned by `GET /connectors/{connector_id}/links`. - `judges` PublicAgentJudgeResponse[], required: Judges for the agent in this environment, with average scores over the matching runs. - `id` string, uuid, required - `name` string, required - `enabled` boolean, required: False when the judge is paused. - `trigger_mode` string, required: `automatic` evaluates runs as they complete; `manual` evaluates only when triggered. - `avg_score` number, nullable, required: Average overall score of completed evaluations for the matching runs. Null when none. - `avg_max_score` number, nullable, required: Average maximum possible score of those evaluations. Null when none. ## Other responses - `401`: Missing or invalid API key. - `403`: The API key lacks the required permission or access to the environment. - `404`: The resource does not exist in this project. - `422`: Validation Error - `429`: Rate limit exceeded. --- [API](https://skmtc.dev/connic/apis/connic-api.md) · [All operations](https://skmtc.dev/connic/apis/connic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/connic/apis/connic-api/revisions/482932da5fbe?raw)