> ## Documentation Index > Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-fjmorr-1782499519-e1e0dbe.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # List agents > Returns the agents the authenticated user has access to. The default `audience=user` view returns the agents the caller owns plus any agents that have been directly shared with the caller via `permissions.shared_users`. The alternate `audience=tenant` view returns only the workspace-shared agents (those whose `permissions.visibility` is `tenant`). System-created defaults are always excluded. Each item carries two caller-relative fields that describe the authenticated user's relationship to that agent: * `is_owner` — `true` if the caller is the agent's owner. * `access_level` — one of `READ`, `RUN`, or `WRITE`. Owners get `WRITE`. Direct shares get the level matching the `shared_users` list they appear in. Tenant-shared rows get the agent's `tenant_access_level`. The maximum applicable level always wins. Results are cursor-paginated. Pass the `cursor` value from the previous response to fetch the next page; `next_cursor` is omitted when no further pages exist. ## OpenAPI ````yaml /langsmith/headless-fleet-openapi.json get /v1/fleet/agents openapi: 3.0.0 info: contact: {} description: > The Fleet API is a headless interface for building and running agents — create and configure agents, manage their connections and secrets, run threads, and wire up triggers. Paths are service-native (e.g. `/v1/fleet/agents`). Self-hosted deployments reach them through the gateway under an `/api` prefix (e.g. `/api/v1/fleet/agents`). ## Authentication Every request must carry **one** credential: | Scheme | Header | Value | | --- | --- | --- | | API key | `X-Api-Key` | A LangSmith API key (`lsv2_…`). | | Session token | `Authorization` | `Bearer `. | Workspace-scoped endpoints additionally require **`X-Tenant-Id`**, set to the workspace (tenant) UUID the request operates in. Organization- and identity-scoped endpoints omit it. ## Errors Errors follow [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) (Problem Details) and use one JSON shape across every endpoint: ```json { "type": "about:blank", "code": "agent_not_found", "detail": "No agent exists with that ID.", "status": 404 } ``` - `type` — URI identifying the error type. Currently always `about:blank` (the RFC 7807 default); branch on `code`, not `type`. - `code` — stable, machine-readable identifier. Branch on this rather than matching `detail`. - `detail` — human-readable explanation. Proxied endpoints also echo it as `message`. - `status` — mirrors the HTTP status code. | Status | Meaning | | --- | --- | | `400` | Malformed request or failed validation. | | `401` | Missing or invalid credentials. | | `403` | Authenticated, but not permitted to access this resource. | | `404` | The resource does not exist or is not visible to your workspace. | | `409` | Conflicts with current state (e.g. a duplicate). | | `422` | Well-formed but semantically invalid. | | `500` | Unexpected server error. | | `502` / `503` | An upstream dependency failed or was unavailable. Retries are usually safe. | ## Pagination List endpoints return a fixed-size page and an opaque cursor: ```json { "items": [ ], "next_cursor": "eyJ…" } ``` - `page_size` — items per page, `1`–`100` (default `20`). - `cursor` — pass the previous response's `next_cursor` to fetch the next page. An absent or empty `next_cursor` means there are no more results. Cursors are opaque — don't construct or parse them. title: Fleet API version: v1 servers: - url: / security: [] tags: - name: agents - name: agent connections - name: threads - name: skills - name: auth - name: integrations - name: secrets - name: models - name: tenants - name: users paths: /v1/fleet/agents: get: tags: - agents summary: List agents description: |- Returns the agents the authenticated user has access to. The default `audience=user` view returns the agents the caller owns plus any agents that have been directly shared with the caller via `permissions.shared_users`. The alternate `audience=tenant` view returns only the workspace-shared agents (those whose `permissions.visibility` is `tenant`). System-created defaults are always excluded. Each item carries two caller-relative fields that describe the authenticated user's relationship to that agent: * `is_owner` — `true` if the caller is the agent's owner. * `access_level` — one of `READ`, `RUN`, or `WRITE`. Owners get `WRITE`. Direct shares get the level matching the `shared_users` list they appear in. Tenant-shared rows get the agent's `tenant_access_level`. The maximum applicable level always wins. Results are cursor-paginated. Pass the `cursor` value from the previous response to fetch the next page; `next_cursor` is omitted when no further pages exist. parameters: - description: Items per page (1-100). Default 20. name: page_size in: query schema: type: integer - description: Opaque pagination cursor returned by the previous list call. name: cursor in: query schema: type: string - description: Case-insensitive substring filter on the agent name. name: name in: query schema: type: string - description: >- Scope of agents to return. `user` (default) returns owned + directly-shared. `tenant` returns workspace-shared only. name: audience in: query schema: type: string enum: - user - tenant default: user - description: Field to sort by. name: sort_by in: query schema: type: string enum: - created_at - updated_at - name default: updated_at - description: Sort direction. name: sort_order in: query schema: type: string enum: - asc - desc default: desc - description: >- Comma-separated relations to hydrate. `owner` resolves each item's `owner_id` into an `owner` object. Omitted by default to avoid overfetching. `files` is not available on the list endpoint. name: include in: query schema: type: string enum: - owner responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/agents.ListAgentsResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/agents.ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/agents.ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/agents.ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/agents.ErrorResponse' '502': description: Bad Gateway content: application/json: schema: $ref: '#/components/schemas/agents.ErrorResponse' '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/agents.ErrorResponse' security: - API_Key: [] - Tenant_ID: [] - Bearer_Auth: [] components: schemas: agents.ListAgentsResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/agents.AgentSummary' next_cursor: type: string agents.ErrorResponse: type: object properties: code: type: string detail: type: string status: type: integer type: type: string agents.AgentSummary: type: object properties: access_level: description: The caller's access level on this agent. type: string enum: - READ - RUN - WRITE example: WRITE backend: $ref: '#/components/schemas/agents.AgentBackend' created_at: type: string format: date-time example: '2026-01-15T09:30:00Z' description: type: string example: Researches topics and drafts summaries. display: $ref: '#/components/schemas/agents.AgentDisplay' extras: type: object additionalProperties: {} id: type: string format: uuid example: 11111111-1111-1111-1111-111111111111 is_owner: description: True when the caller owns this agent. type: boolean example: true model: $ref: '#/components/schemas/agents.AgentModel' name: type: string example: Research Assistant options: $ref: '#/components/schemas/agents.AgentOptions' owner: $ref: '#/components/schemas/users.UserRef' owner_id: type: string format: uuid example: 7f8e9d0c-1b2a-3948-5766-8594a3b2c1d0 permissions: $ref: '#/components/schemas/agents.AgentPermissions' updated_at: type: string format: date-time example: '2026-01-15T09:30:00Z' agents.AgentBackend: type: object properties: sandbox_config: description: >- Sandbox configuration. Required when `type` is `sandbox`, rejected otherwise. allOf: - $ref: '#/components/schemas/agents.SandboxConfig' type: description: >- Execution backend. Defaults to `state` when omitted (along with the whole `backend` object). `state` runs without a sandbox: files live in LangGraph thread state, which is thread-scoped — they persist across turns within a thread but are not shared across threads. `sandbox` provisions an isolated computer. type: string enum: - state - sandbox example: sandbox agents.AgentDisplay: type: object properties: icon: type: string example: Rocket02 icon_color: type: string example: blue agents.AgentModel: type: object properties: id: description: >- Model id from GET /v1/fleet/models. Built-in ids are `provider:model` (e.g. anthropic:claude-sonnet-4-6); workspace (custom) models use the workspace model id. type: string example: anthropic:claude-sonnet-4-6 agents.AgentOptions: type: object properties: skip_memory_write_protection: description: >- Internal. Disables the human approval interrupt before memory writes. type: boolean x-internal: true slack_oauth_provider_id: description: Internal. Slack OAuth provider the agent posts replies as. type: string x-internal: true tools_url: description: >- Internal. MCP tool server the agent connects to; defaults to the platform server when empty. type: string x-internal: true trace_inputs_outputs: description: Whether the agent records run inputs/outputs to its tracing project. type: boolean triggers_paused: description: Internal. Not needed. type: boolean x-internal: true user_timezone: description: >- Default IANA timezone for runs that don't supply one (e.g. trigger-fired runs with no browser). Interactive runs inject the live timezone per-run and override this. Defaults to UTC on create when omitted. type: string example: America/New_York users.UserRef: type: object properties: id: type: string format: uuid name: type: string example: Ada Lovelace agents.AgentPermissions: type: object properties: identity: type: string enum: - personal - shared shared_users: $ref: '#/components/schemas/agents.SharedUsers' tenant_access_level: type: string enum: - read - run - write visibility: type: string enum: - tenant - user agents.SandboxConfig: type: object properties: delete_after_stop_seconds: description: Time after a sandbox is stopped before it is deleted, in seconds. type: integer example: 1200 idle_ttl_seconds: description: Idle timeout after which an unused sandbox is paused, in seconds. type: integer example: 600 policy_ids: description: Sandbox policies governing tool execution. type: array items: type: string sandbox_id: description: Pinned sandbox instance the agent reuses across runs. type: string scope: description: >- Sandbox lifecycle. `thread` gives each thread its own sandbox; `agent` shares one sandbox across all of the agent's threads. Required when `backend.type` is `sandbox`. type: string enum: - thread - agent example: thread snapshot_id: description: Snapshot used when creating new sandbox-backed computers. type: string example: 550e8400-e29b-41d4-a716-446655440000 agents.SharedUsers: type: object properties: read: description: User IDs allowed to read the agent. type: array items: type: string run: description: User IDs allowed to run the agent. type: array items: type: string update: description: User IDs allowed to update the agent. type: array items: type: string securitySchemes: API_Key: description: LangSmith API key (`lsv2_...`). type: apiKey name: X-Api-Key in: header Tenant_ID: description: Workspace (tenant) UUID the request operates in. type: apiKey name: X-Tenant-Id in: header Bearer_Auth: description: Session JWT, sent as `Bearer `. type: apiKey name: Authorization in: header ````