Lister les agents connectés à l’organisation authentifiée

GET/api/public/v1/agents

Returns one row per agent (one platform used on one host by one OS user in one profile) within the caller's organization, ordered by most-recently-seen first. Includes a 24h verdict breakdown joined from event_stats_daily. Paginated with page/page_size. The five ownership filters (owner / function / org_unit / unattributed / owner_status) narrow the list, and every row carries the six ownership fields (owner_kind / owner_person_id / owner_display_name / owner_status / function / org_unit_path). zone_id, assignment_source, environment, category, control_level and q narrow it further, and every row names the zone that governs the agent (assigned_zone_id, assigned_zone_unit_id, assigned_zone_label, assignment_source).

cURL

curl --fail-with-body -X GET 'https://app.openlatch.ai/api/public/v1/agents?page=1&page_size=50' \
  -H "Authorization: Bearer $OPENLATCH_API_KEY"

Python

import json
import os
import urllib.request

request = urllib.request.Request(
    'https://app.openlatch.ai/api/public/v1/agents?page=1&page_size=50',
    method='GET',
    headers={
        'Authorization': 'Bearer ' + os.environ['OPENLATCH_API_KEY'],
    },
)
with urllib.request.urlopen(request) as response:
    text = response.read().decode()
    print(json.dumps(json.loads(text), indent=2) if text else response.status)

Bash

#!/usr/bin/env bash
set -euo pipefail

curl -sS --fail-with-body -X GET 'https://app.openlatch.ai/api/public/v1/agents?page=1&page_size=50' \
  -H "Authorization: Bearer $OPENLATCH_API_KEY" | jq .

PowerShell

$headers = @{
  Authorization = "Bearer $env:OPENLATCH_API_KEY"
}
Invoke-RestMethod -Method GET -Uri 'https://app.openlatch.ai/api/public/v1/agents?page=1&page_size=50' -Headers $headers | ConvertTo-Json -Depth 20

Autorisation

Rôle dans l’organisation	Ce point de terminaison
owner	Autorisé
admin	Autorisé
editor	Autorisé
viewer	Autorisé

Une clé porte le rôle que son propriétaire détient dans l’organisation. Voir Authentification.

Portée de clé d’API : agents:read

Paramètres de requête

Paramètre	Type	Description
page	integer	1-indexed page number
page_size	integer	Page size (max 200)
platform	array of string or null	Filter to one or more agent platforms (repeat the param)
window	string — one of 24h, 7d, 30d, 90d	Rolling window for the per-agent action_mix rollup. One of 24h, 7d, 30d, 90d. Does not affect verdicts_24h, which always reflects the last 24h.
compatibility	string or null	unavailable narrows to installs whose latest compatibility evidence does not intersect what the platform currently retains.
capability_limit	string — one of cannot_prompt, shell_only or null	Narrow to the agents whose binding limits what an ASK can do: cannot_prompt (its ASKs take the fallback verdict) or shell_only (its refusals reach shell tools only). An install that has not reported is never in either set.
host_id	string or null	Narrow to the agents reporting from one licensed host.
zone_id	string (uuid) or null	Narrow to the agents whose assigned zone (manual pin, else the resolver's) is this zone.
assignment_source	string — one of auto, manual or null	manual — pinned to a zone by hand; auto — the resolver decides.
environment	array of string or null	Narrow to these environments (repeat the param).
category	array of string or null	Narrow to these categories (repeat the param).
control_level	array of string — one of enforced, monitored, known or null	Narrow to these derived control levels (repeat the param).
q	string or null	Free text over display name, agent id, platform and the owner's display name.
owner	array of string	Agents whose resolved human owner is any of these directory_people ids (repeat the param).
function	array of string	Agents whose business function is any of these frozen-enum values (repeat the param). An unknown value is a 400, never an empty list.
org_unit	array of string	Agents whose placement unit (the human owner's unit, else the service-accountable person's unit, else the service-accountable unit) is any of these org_units ids OR any descendant (repeat the param). Descendants are resolved server-side.
unattributed	boolean	Only agents with owner_kind = 'unattributed' (the PRD literal). Deliberately EXCLUDES owner_kind IS NULL (still resolving) and a human owner whose person row is gone.
owner_status	string or null	Only 'inactive' is accepted: agents whose owner exists AND is marked inactive in the directory.

Réponse

• 200 OK — l’appel a réussi.
• 400 Bad Request — BAD_REQUEST
• 401 Unauthorized — UNAUTHORIZED
• 402 Payment Required — license_expired
• 403 Forbidden — FEATURE_DISABLED, FORBIDDEN, INSUFFICIENT_SCOPE
• 422 Unprocessable Content — INVALID_ID, VALIDATION_ERROR
• 429 Too Many Requests — TOO_MANY_REQUESTS
• 500 Internal Server Error — INTERNAL_SERVER_ERROR, tenant_isolation_violation
• 503 Service Unavailable — FEATURE_STATE_UNAVAILABLE, SERVICE_UNAVAILABLE

Champs de la réponse

Champ	Type	Description
data	array of object	Obligatoire.
data[].action_mix	object	Domain / file / command action counts rolled up from the agent_action_* tables, scoped to the window supplied by the caller (defaults to 24h). Zero across the board means no actionable events were extracted in the window.
data[].action_mix.commands	integer
data[].action_mix.domains	integer
data[].action_mix.files	integer
data[].agent_id	string	Obligatoire.
data[].assigned_zone_id	string or null	The zone governing this agent: its manual pin, else the one the resolver gives it.
data[].assigned_zone_label	string or null	The assigned zone's org-unit name — the label every zone surface shows.
data[].assigned_zone_unit_id	string or null	The org unit the assigned zone hangs off.
data[].assignment_source	string — one of auto, manual	manual — pinned to a zone by hand; auto — the resolver decides.
data[].budget_source	string	Which scope produced budget_usd: agent | subscription_default | org_default | none.
data[].budget_usd	string or null	The resolved monthly budget - this agent's own row, else the default of the declared subscription that makes it Sanctioned, else the org default. Null when none is set.
data[].category	string or null	Open category string; known values coding | analysis | ops | content | service.
data[].control_level	string	enforced (fetched a bundle in the last 24h — evaluating policy locally) | monitored (sent events, no bundle — we see it and cannot stop it) | known (neither). Derived per request, never stored.
data[].display_name	string or null
data[].environment	string	Frozen Environment — production | staging | development | unknown.
data[].first_seen_at	string (date-time)	Obligatoire.
data[].function	string or null	Business function (frozen enum; wire name for the ORM's business_function). 'unknown' = not yet classified; null while the resolver has not yet run.
data[].host_id	string or null
data[].instance_qualifier	object or null	What tells this agent apart from the other agents of its platform on its host, shown beside the name and never inside it; null for a host's first OS user in their default profile.
data[].last_seen_at	string (date-time)	Obligatoire. When the agent last sent activity. For an agent that has never been active (found by discovery, never run since), this is first_seen_at and never_active is true.
data[].latest_agent_version	string or null
data[].latest_arch	string or null
data[].latest_client_version	string or null
data[].latest_hook_version	string or null
data[].latest_local_ipv4	string or null
data[].latest_local_ipv6	string or null
data[].latest_os	string or null
data[].latest_public_ipv4	string or null
data[].latest_public_ipv6	string or null
data[].mtd_consumption_usd	string or null	Month-to-date consumption for this agent (pricebook-weighted cost_total, every billing mode). What the budget is measured against. Null when the surface did not compute it; 0 means the agent really has not spent.
data[].never_active	boolean	True when the agent has never sent any activity (found by discovery and not run since): last_seen_at then repeats first_seen_at and is not a sighting of activity.
data[].org_unit_path	string or null	Slash-joined path of the agent's placement unit: the human owner's unit, else the service-accountable person's unit, else the service-accountable unit. Null when none applies.
data[].owner_display_name	string or null	The owner person's display name; null when there is no (or an orphaned) owner person.
data[].owner_kind	string or null	Ownership verdict: human | service | unattributed; null while the resolver has not yet run.
data[].owner_person_id	string or null	The resolved human owner's directory_people id — the value the owner filter of GET /agents takes (it cannot filter by display name). Null for service / unattributed / resolving.
data[].owner_status	string or null	The owner person's directory status (active | inactive); null when there is no owner person.
data[].platform	string	Obligatoire.
data[].proxy_as_of	string (date-time) or null	Timestamp of the latest event that actually CARRIED the proxy attributes — not of the latest event overall, so a stale shape is never reported as freshly confirmed. Null until the first carrying event.
data[].proxy_source	string or null	How the client found that route: manual | env | windows | macos | gnome | pac | wpad. Null under the same conditions as proxy_type. Open string, same reason.
data[].proxy_tls_intercepted	boolean or null	Whether the client observed the proxy terminating and re-issuing TLS. Null is NOT false: null = never observed (the client omits the attribute until a TLS handshake has actually completed), false = observed and clean.
data[].proxy_type	string or null	Egress proxy type last reported by this agent's client: http | https | socks5 | pac. Null = the agent egresses direct, or never reported one. Open string: the client owns the vocabulary, so an unknown value is stored and returned verbatim rather than rejected.
data[].sessions_count	integer	Distinct session count for this agent over the same rolling window as action_mix (defaults to 24h): how many sessions blend into one agent identity, without a per-agent sessions call. Zero means no sessions were active in the window.
data[].stale	boolean	This install's latest compatibility evidence (I-15 plan 02) does not intersect what the platform currently retains. NOT a fourth control level: a stale agent keeps whatever level its last bundle earned it, because 'we stopped serving it' and 'it is not under control' are different facts.
data[].total_events_lifetime	integer	Lifetime event count for this agent — sum of event_stats_daily.event_count across every day, never zero-floored to a 24h window. Gives an accurate count for agents idle longer than 24h, for which verdicts_24h shows 0 even when the agent has many events in older sessions.
data[].used_pct	number or null	mtd_consumption_usd as a percent of budget_usd. Null when there is no budget. A zero budget reports 100 when nothing was spent and 999 otherwise.
data[].verdicts_24h	object	Verdict counts over the last 24h. Zero if no activity.
data[].verdicts_24h.allow	integer	Actions the policy allowed
data[].verdicts_24h.ask	integer	Actions the policy sent to Ask
data[].verdicts_24h.block	integer	Actions the policy blocked
data[].verdicts_24h.total	integer	Total events in the 24h window
data[].window_consumption_usd	string or null	Consumption for this agent over the request's window (pricebook-weighted cost_total, every billing mode) — the figure the fleet tile prints. Never compare it to budget_usd: a budget is a calendar month. Null when the surface did not compute it; 0 means the agent really has not spent in the window.
page	integer	Obligatoire.
page_size	integer	Obligatoire.
total	integer	Obligatoire.

Exemple de réponse

{
  "data": [
    {
      "action_mix": {
        "commands": 0,
        "domains": 0,
        "files": 0
      },
      "agent_id": "agt_01jbwa2k1vfrn9y42xhgxhmzj2",
      "assigned_zone_id": "3f6c1a2e-8b4d-4c1f-9a7e-0d5b2c8e4f10",
      "assigned_zone_label": "string",
      "assigned_zone_unit_id": "3f6c1a2e-8b4d-4c1f-9a7e-0d5b2c8e4f10",
      "assignment_source": "auto",
      "budget_source": "none",
      "budget_usd": "string",
      "category": "string",
      "control_level": "known",
      "display_name": "release-bot",
      "environment": "production",
      "first_seen_at": "2026-01-15T14:32:05Z",
      "function": "string",
      "host_id": "hst_01jbwa2k1vfrn9y42xhgxhmzj2",
      "instance_qualifier": {
        "os_user": "string",
        "profile_suffix": "string",
        "user_suffix": "string"
      },
      "last_seen_at": "2026-01-15T14:32:05Z",
      "latest_agent_version": "string",
      "latest_arch": "string",
      "latest_client_version": "string",
      "latest_hook_version": "string",
      "latest_local_ipv4": "string",
      "latest_local_ipv6": "string",
      "latest_os": "string",
      "latest_public_ipv4": "string",
      "latest_public_ipv6": "string",
      "mtd_consumption_usd": "string",
      "never_active": false,
      "org_unit_path": "Engineering / Platform",
      "owner_display_name": "release-bot",
      "owner_kind": "string",
      "owner_person_id": "3f6c1a2e-8b4d-4c1f-9a7e-0d5b2c8e4f10",
      "owner_status": "string",
      "platform": "string",
      "proxy_as_of": "2026-01-15T14:32:05Z",
      "proxy_source": "string",
      "proxy_tls_intercepted": false,
      "proxy_type": "string",
      "sessions_count": 0,
      "stale": false,
      "total_events_lifetime": 0,
      "used_pct": 0.25,
      "verdicts_24h": {
        "allow": 0,
        "ask": 0,
        "block": 0,
        "total": 0
      },
      "window_consumption_usd": "string"
    }
  ],
  "page": 1,
  "page_size": 3,
  "total": 3
}

Voir aussi

• DELETE Supprimer un agent, avec ses sessions, ses événements et ses statistiques.
• GET Obtenir un agent par son ID
• PATCH Modifier les champs modifiables d’un agent (actuellement : display_name).