---
title: "List agents"
method: GET
path: "/v1/agents"
---

# List agents

`GET /v1/agents`

## Request

- Base URL: `https://api.runbear.io`
- URL: `https://api.runbear.io/v1/agents`
- Auth: HTTP bearer

List detailed configuration information for multiple agents. Returns agent settings including LLM provider, system prompt, advanced options, and integration status.

## Query parameters

- `ids` string, required: Comma-separated list of agent IDs to retrieve information for (max 100)

## Response `200`

Default Response

- AgentInformationList
  - `agents` AgentInformation[], required: Array of agent information objects
    - `id` string, uuid, required: Unique identifier for the agent
    - `name` string, required: Name of the agent
    - `systemPrompt` string, nullable, required: The system prompt stored for this agent on Runbear. This is the configured prompt, not the fully composed one: agents that support context blocks append them to it at invocation time.
    - `provider` union, required: Provider-specific options
      - object
        - `type` 'anthropic', required
        - `model` string, required
        - `pinModelVersion` boolean, required: Whether the agent holds `model` exactly (a specific version). `false` means automatic latest: the agent follows Runbear's current stable model in the same family or tier, so `effectiveModel` can differ from `model`. OpenAI models without a tier (such as `gpt-5.5` or `gpt-4o`) are always served as stored, and so is an older Gemini model whose tier's current model costs more.
        - `effectiveModel` string, required: The model the agent runs on when a request does not override it. Equals `model` when `pinModelVersion` is true; otherwise the current stable model in the same family or tier, resolved at read time.
        - `useOwnApiKey` boolean, required: Whether the organization uses their own provider API key
        - `thinking` union: Extended thinking configuration
          - object
            - `type` 'enabled', required
            - `budgetTokens` number, required
            - `effort` 'low' | 'medium' | 'high' | 'xhigh' | 'max': How much reasoning the model spends per turn when extended thinking is enabled. Defaults to `medium` when omitted, which is what every agent ran at before this field existed. `xhigh` and `max` consume substantially more thinking tokens — on Runbear's managed key that shows up directly as higher credit usage. Only the adaptive-thinking models (claude-haiku-5-5, claude-sonnet-5-5, claude-fable-5-1, claude-opus-5-5, claude-opus-5, claude-fable-5, claude-sonnet-5, claude-opus-4-8, claude-opus-4-7) act on this; older models use a token budget instead and store the value without effect, so it applies if the agent is later moved to an adaptive model.
          - object
            - `type` 'disabled', required
        - `temperature` number, nullable: Temperature value for response generation
      - object
        - `type` 'openai-responses', required
        - `model` string, required
        - `pinModelVersion` boolean, required: Whether the agent holds `model` exactly (a specific version). `false` means automatic latest: the agent follows Runbear's current stable model in the same family or tier, so `effectiveModel` can differ from `model`. OpenAI models without a tier (such as `gpt-5.5` or `gpt-4o`) are always served as stored, and so is an older Gemini model whose tier's current model costs more.
        - `effectiveModel` string, required: The model the agent runs on when a request does not override it. Equals `model` when `pinModelVersion` is true; otherwise the current stable model in the same family or tier, resolved at read time.
        - `useOwnApiKey` boolean, required: Whether the organization uses their own provider API key
        - `reasoning` object: Reasoning configuration for reasoning models
          - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh', nullable: Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.
          - `summary` 'auto' | 'concise' | 'detailed', nullable: A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process.
        - `text` object: Configuration for response text output
          - `format` union: Response format configuration
            - object
              - …
            - object
              - …
            - object
              - …
          - `verbosity` 'low' | 'medium' | 'high', nullable: The verbosity level of the response text. Can be low, medium, or high.
      - object
        - `type` 'gemini', required
        - `model` string, required
        - `pinModelVersion` boolean, required: Whether the agent holds `model` exactly (a specific version). `false` means automatic latest: the agent follows Runbear's current stable model in the same family or tier, so `effectiveModel` can differ from `model`. OpenAI models without a tier (such as `gpt-5.5` or `gpt-4o`) are always served as stored, and so is an older Gemini model whose tier's current model costs more.
        - `effectiveModel` string, required: The model the agent runs on when a request does not override it. Equals `model` when `pinModelVersion` is true; otherwise the current stable model in the same family or tier, resolved at read time.
        - `useOwnApiKey` boolean, required: Whether the organization uses their own provider API key
      - object
        - `type` 'claude-agent-sdk', required
        - `model` string, required
        - `pinModelVersion` boolean, required: Whether the agent holds `model` exactly (a specific version). `false` means automatic latest: the agent follows Runbear's current stable model in the same family or tier, so `effectiveModel` can differ from `model`. OpenAI models without a tier (such as `gpt-5.5` or `gpt-4o`) are always served as stored, and so is an older Gemini model whose tier's current model costs more.
        - `effectiveModel` string, required: The model the agent runs on when a request does not override it. Equals `model` when `pinModelVersion` is true; otherwise the current stable model in the same family or tier, resolved at read time.
        - `useOwnApiKey` boolean, required: Whether the organization uses their own provider API key
    - `tools` ToolsConfig, required
      - `requireApprovalForResourceChanges` boolean: Whether approval is required for resource changes
      - `requireApprovalBeforeToolCalls` boolean: Whether approval is required before any tool call. When enabled, supersedes requireApprovalForResourceChanges.
      - `integrations` ManagedToolIntegration[]: List of enabled managed tool integrations
        - `type` 'managed', required
        - `id` 'webSearch' | 'codeInterpreter' | 'imageInterpretation' | 'dalleImageGeneration' | 'urlFetch' | 'currentDateFetching', required: Managed tool integration ID
        - `name` string, required: Name of the integration
    - `longTermMemory` object, required: Long-term memory configuration. When enabled, the agent remembers user preferences and frequently referenced resources across conversations.
      - `enabled` boolean, required: Whether long-term memory is enabled
    - `toolProgress` object, required: Tool activity configuration. When disabled, `thread.tool_call.progress` events are withheld from the streaming API and no tool cards are posted to the chat channels; the agent still runs the same tools and the run trace still records them. Enabled does not guarantee events — a runtime that reports no tool activity has none to send.
      - `enabled` boolean, required: Whether tool activity is surfaced to the caller
    - `responseComponents` ResponseComponents, required: Interactive response component configuration: how often the agent answers with a component (`frequency`; absent from storage means "off") and which components it may use (`components`).
      - `frequency` string, required: How often the agent is nudged to answer with an interactive response component. Currently one of: off, low, medium, high. New levels may be appended, so treat this as an open string rather than a closed union. "off" withholds the tool entirely; an agent whose type cannot emit response components reports "off" unless the dial was set while its type still supported them.
      - `components` ResponseComponentToggles, required: Resolved per-component switches: always every switch this deployment knows, with defaults filled in. New switches may be appended; treat unknown keys as additional switches, not an error. A switch is configuration, not a promise: the agent's type, the frequency dial and the agent's Choice Buttons setting also apply.
        - `choiceButtons` boolean, required: The confirm and select components on the Web SDK (one tool). Default on. Web only; the agent's global Choice Buttons setting (disableInteractivePrompts) still overrides it.
        - `card` boolean, required: The card component on the Web SDK. Default on.
        - `list` boolean, required: The list component on the Web SDK. Default off.
        - `table` boolean, required: The table component on the Web SDK. Default off.
        - `chart` boolean, required: The chart component on the Web SDK. Default off.
    - `knowledgeSearch` KnowledgeSearch, required: Knowledge base search tuning parameters. Controls how knowledge base search results are ranked and filtered.
      - `maxResults` integer, required: Maximum documents returned per knowledge base search (1–50).
      - `scoreThreshold` number, required: Minimum relevance score to include a result (0–1). Lower means higher recall.
      - `semanticWeight` number, required: Weight for semantic/embedding matching vs keyword matching (0–1). 0 = all keyword, 1 = all semantic. Only effective for providers that support hybrid search (Anthropic, Gemini, Upstage). OpenAI Responses agents ignore this value.
    - `aiGateway` AiGatewayResponse
      - `cloudflareAccountId` string, required: Cloudflare account ID
      - `gatewayName` string, required: Cloudflare AI Gateway name
      - `enabled` boolean, required: Whether routing through the gateway is active
      - `source` 'agent' | 'organization', required: Where the active gateway config comes from — agent-level override or organization default
    - `timeoutMinutes` integer, required: Maximum execution time in minutes for a single chat completion. Defaults to 6 minutes; capped at 20 minutes.
    - `createdAt` string, required: ISO 8601 timestamp when the agent was created
    - `lastModifiedAt` string, required: ISO 8601 timestamp of the last update to the agent record. May reflect system-driven updates, not only user edits.
    - `channels` string[], required: Connected communication channels (slack, teams, discord, hubspot, zendesk)
    - `toolIntegrations` ToolIntegration[], required: User-attached MCP, Pipedream, and Custom MCP integrations. Distinct from `tools.integrations`, which lists provider-builtin tools (webSearch, codeInterpreter, ...). Empty for agent types that don't support tool integrations.
      - union: A tool integration attached to an agent. Discriminated on `type`: `managed-mcp` (Runbear-managed MCP server), `pipedream` (Pipedream connector), or `custom-mcp` (caller-hosted MCP server).
        - object
          - `id` string, uuid, required: Tool integration ID.
          - `status` 'ready' | 'pending_auth', required: Connection health. `ready` means the integration is fully authorized and callable. `pending_auth` means the user must complete OAuth (or otherwise complete setup) before tools are usable.
          - `createdAt` string, required
          - `updatedAt` string, required
          - `excludedTools` string[]: Tools excluded from the agent's toolbox by name.
          - `type` 'managed-mcp', required
          - `app` string, required: Managed MCP catalog slug (e.g., "notion").
        - object
          - `id` string, uuid, required: Tool integration ID.
          - `status` 'ready' | 'pending_auth', required: Connection health. `ready` means the integration is fully authorized and callable. `pending_auth` means the user must complete OAuth (or otherwise complete setup) before tools are usable.
          - `createdAt` string, required
          - `updatedAt` string, required
          - `excludedTools` string[]: Tools excluded from the agent's toolbox by name.
          - `type` 'pipedream', required
          - `nameSlug` string, required: Pipedream app slug (e.g., "firecrawl", "aws").
          - `authType` 'keys' | 'oauth' | 'none', nullable, required: Authentication style required by the Pipedream app.
        - object
          - `id` string, uuid, required: Tool integration ID.
          - `status` 'ready' | 'pending_auth', required: Connection health. `ready` means the integration is fully authorized and callable. `pending_auth` means the user must complete OAuth (or otherwise complete setup) before tools are usable.
          - `createdAt` string, required
          - `updatedAt` string, required
          - `excludedTools` string[]: Tools excluded from the agent's toolbox by name.
          - `type` 'custom-mcp', required
          - `app` string, required: Display label for the MCP server.
          - `url` string, required: Remote MCP server URL.
          - `transportType` 'sse' | 'streamableHttp', required
          - `auth` union, required
            - object
              - …
            - object
              - …
            - object
              - …
          - `httpHeaders` object: HTTP headers forwarded to the MCP server. Vault-backed values expose only `keyName`, never the secret value.

---

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