---
title: "List Agents"
method: GET
path: "/agents"
tags: ["agents"]
---

# List Agents

`GET /agents`

## Request

- Base URL: `https://api.instruxi.dev/api/v1/enforcer`
- URL: `https://api.instruxi.dev/api/v1/enforcer/agents`
- Auth: one of:
  - API key in header `Authorization`
  - API key in header `X-API-Key`

Agents the caller can see (viewer()): the whole tenant for a caller with a tenant-wide read grant, otherwise the agents they steward or reach through a group. `owner` is `me` (agents I own or steward), `account:<id>` or `group:<id>`. ADR 0003 paging. An unknown query key is 400 unknown_param.

## Query parameters

- `owner` string
- `state` string
- `q` string
- `limit` integer
- `offset` integer

## Response `200`

OK

- InternalDeliveryHttpHandlerAgentListResponse
  - `data` InternalDeliveryHttpHandlerAgentListPage
    - `filtered` integer
    - `items` EnforcerV3InternalUsecaseAgentsView[]
      - `card` object
      - `created_at` string
      - `created_by` string
      - `credentials` EnforcerV3InternalUsecaseAgentsCredentialRollup
        - `active` integer
        - `expiring_within_7d` integer
        - `last_used_at` string
      - `description` string
      - `effective_permissions` EnforcerV3InternalAuthzPermissions
        - `admin_managed` boolean: read/write/manage admin-managed types in tenant
        - `cross_tenant` boolean: every row, every tenant (admin)
        - `mpp_ops` boolean: MPPOps is a NARROW operator grant: read the MPP deposit-intent queue and its settle plans across tenants (GET /admin/mpp-deposit-intents...). It moves no money (the settle/refund levers stay PlatformOnly) and the policy never reads it: no row anywhere else becomes visible through it.
        - `tenant_manage` boolean: manage any non-admin-managed row in tenant
        - `tenant_read` boolean: read any non-admin-managed row in tenant
        - `tenant_write` boolean: write any non-admin-managed row in tenant
      - `expires_at` string
      - `groups` EnforcerV3InternalUsecaseAgentsGroupRef[]
        - `id` string
        - `name` string
        - `slug` string
      - `id` string
      - `name` string
      - `owner` EnforcerV3InternalUsecaseAgentsOwnerView
        - `id` string
        - `kind` 'account' | 'group'
        - `name` string
      - `rate_limit_per_min` integer
      - `role` EnforcerV3InternalUsecaseAgentsRoleView
        - `id` string
        - `permissions` EnforcerV3InternalAuthzPermissions
          - `admin_managed` boolean: read/write/manage admin-managed types in tenant
          - `cross_tenant` boolean: every row, every tenant (admin)
          - `mpp_ops` boolean: MPPOps is a NARROW operator grant: read the MPP deposit-intent queue and its settle plans across tenants (GET /admin/mpp-deposit-intents...). It moves no money (the settle/refund levers stay PlatformOnly) and the policy never reads it: no row anywhere else becomes visible through it.
          - `tenant_manage` boolean: manage any non-admin-managed row in tenant
          - `tenant_read` boolean: read any non-admin-managed row in tenant
          - `tenant_write` boolean: write any non-admin-managed row in tenant
        - `slug` string
      - `scopes` string[]
      - `service_account` EnforcerV3InternalUsecaseAgentsServiceAccountView
        - `active` boolean
        - `agent_id` string
        - `created_at` string
        - `created_by` string
        - `description` string
        - `email` string
        - `groups` EnforcerV3InternalUsecaseAgentsGroupRef[]
          - `id` string
          - `name` string
          - `slug` string
        - `id` string
        - `key_count` integer
        - `kind` string
        - `last_used_at` string
        - `name` string
        - `role` EnforcerV3InternalUsecaseAgentsRoleView
          - `id` string
          - `permissions` EnforcerV3InternalAuthzPermissions
            - `admin_managed` boolean: read/write/manage admin-managed types in tenant
            - `cross_tenant` boolean: every row, every tenant (admin)
            - `mpp_ops` boolean: MPPOps is a NARROW operator grant: read the MPP deposit-intent queue and its settle plans across tenants (GET /admin/mpp-deposit-intents...). It moves no money (the settle/refund levers stay PlatformOnly) and the policy never reads it: no row anywhere else becomes visible through it.
            - `tenant_manage` boolean: manage any non-admin-managed row in tenant
            - `tenant_read` boolean: read any non-admin-managed row in tenant
            - `tenant_write` boolean: write any non-admin-managed row in tenant
          - `slug` string
        - `slug` string
        - `tenant_id` string
        - `updated_at` string
      - `slug` string
      - `state` 'active' | 'disabled' | 'suspended'
      - `state_reason` string
      - `steward` EnforcerV3InternalUsecaseAgentsStewardView
        - `account_id` string
        - `email` string
        - `name` string
      - `tenant_id` string
      - `updated_at` string
    - `limit` integer
    - `offset` integer
    - `total` integer
  - `success` boolean

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `503`: Service Unavailable

---

[API](https://skmtc.dev/instruxi/apis/enforcer-api.md) · [All operations](https://skmtc.dev/instruxi/apis/enforcer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/instruxi/apis/enforcer-api/revisions/fa82bc1becc0?raw)