> ## Documentation Index > Fetch the complete documentation index at: https://docs.revoengine.com/llms.txt > Use this file to discover all available pages before exploring further. # Get an Agent overview > Get an Agent overview. The request enforces Agent roles, ownership, workspace boundaries, and lifecycle state. ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/agents/{agentId}/overview openapi: 3.0.0 info: title: RevoEngine Platform API description: Official RevoEngine Platform API documentation. version: 1.3.0 contact: name: Support email: support@revoengine.com termsOfService: https://docs.revoengine.com/tos servers: - url: https://api.revoengine.com description: Production security: [] tags: - name: Accounts description: Users, service accounts, API keys, status, and platform access. externalDocs: description: Identity and access guide url: https://docs.revoengine.com/operate/identity-and-access - name: Activity description: Snapshot-backed activity and version history. externalDocs: description: Observability guide url: https://docs.revoengine.com/operate/observability - name: Agent Memory description: Administrative access to durable Agent memory. externalDocs: description: Agent memory and workspaces guide url: https://docs.revoengine.com/ai/memory-and-workspaces - name: Agent Plugins description: Agent plugin definitions, synchronization, testing, and lifecycle. externalDocs: description: Agent plugins guide url: https://docs.revoengine.com/ai/plugins - name: Agents description: >- Agent definitions, runs, sessions, inboxes, memory, tools, workspaces, and lifecycle. externalDocs: description: Autonomous Agents guide url: https://docs.revoengine.com/ai/agents - name: Assistant description: >- Assistant threads, messages, responses, goals, reports, sharing, attachments, and control. externalDocs: description: Assistant guide url: https://docs.revoengine.com/ai/assistant - name: Automation description: >- Jobs, templates, schedules, events, webhooks, execution history, and lifecycle. externalDocs: description: Automation guide url: https://docs.revoengine.com/operate/automation - name: Chat description: Collaborative chat threads, messages, reactions, uploads, and attachments. externalDocs: description: Team Chat guide url: https://docs.revoengine.com/operate/chat - name: Component deployments description: >- Custom Node.js runtime deployment attempts, readiness, activation, and rollback. externalDocs: description: Custom Node.js guide url: https://docs.revoengine.com/build/custom-nodejs - name: Components description: Components, elements, versions, validation, activation, and lifecycle. externalDocs: description: Components guide url: https://docs.revoengine.com/build/components - name: Config description: Instance configuration, usage, logs, and cache administration. externalDocs: description: Instance settings guide url: https://docs.revoengine.com/platform/instance-settings - name: Database Cache description: Instance Database cache values and statistics. externalDocs: description: Database Cache guide url: https://docs.revoengine.com/operate/database-cache - name: Database Views description: Database Views, previews, refreshes, exports, and controlled data actions. externalDocs: description: Database Views guide url: https://docs.revoengine.com/operate/database-views - name: Databases description: Database definitions, data, audits, exports, cloning, and lifecycle. externalDocs: description: Databases guide url: https://docs.revoengine.com/operate/databases - name: Endpoints description: >- Endpoint definitions, activation, validation, generated OpenAPI, and statistics. externalDocs: description: Endpoints guide url: https://docs.revoengine.com/operate/endpoints - name: Files description: Compatibility file listing, preview, download, and deletion operations. externalDocs: description: Files compatibility guide url: https://docs.revoengine.com/operate/files - name: Groups description: Groups, membership, avatars, and lifecycle. externalDocs: description: Groups guide url: https://docs.revoengine.com/operate/groups - name: Me description: Current user profile, keys, avatar, and session information. externalDocs: description: Authentication guide url: https://docs.revoengine.com/developers/authentication - name: Preferences description: User and instance preference values. externalDocs: description: Platform UI guide url: https://docs.revoengine.com/platform/ui-tour - name: Role Groups description: Role groups, members, assigned roles, and lifecycle. externalDocs: description: Permissions guide url: https://docs.revoengine.com/operate/permissions - name: Roles description: Available platform roles and role details. externalDocs: description: Permissions guide url: https://docs.revoengine.com/operate/permissions - name: Search description: Cross-domain search over objects visible to the caller. externalDocs: description: Search and discovery guide url: https://docs.revoengine.com/platform/search - name: Secrets description: >- Secret definitions, revisions, activation, reveal, disable, and destruction. externalDocs: description: Secrets guide url: https://docs.revoengine.com/operate/secrets - name: Storage description: >- Storage workspaces, folders, objects, upload sessions, signed access, and lifecycle. externalDocs: description: Storage guide url: https://docs.revoengine.com/operate/storage externalDocs: description: Documentation url: https://docs.revoengine.com paths: /api/v1/agents/{agentId}/overview: get: tags: - Agents summary: Get an Agent overview description: >- Get an Agent overview. The request enforces Agent roles, ownership, workspace boundaries, and lifecycle state. operationId: AgentController_getAgentOverview parameters: - name: agentId required: true in: path schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/AgentOverviewDto' security: - bearer: [] components: schemas: AgentOverviewDto: type: object properties: agent: description: Agent definition. example: agentId: 99999999-9999-4999-8999-999999999999 name: Release Reporter allOf: - $ref: '#/components/schemas/AgentPublicDto' workspaceMode: type: string description: Workspace source shown by agent overview clients. enum: - MANAGED - EXISTING example: MANAGED summary: description: Operational summary for the agent. example: activeRunCount: 1 queuedInboxCount: 3 attachedPluginCount: 2 allOf: - $ref: '#/components/schemas/AgentSummaryDto' required: - agent - workspaceMode - summary AgentPublicDto: type: object properties: agentId: type: string description: Stable agent id. example: 99999999-9999-4999-8999-999999999999 name: type: string description: Agent display name. example: Release Reporter status: type: string description: Agent lifecycle status. enum: - ACTIVE - PAUSED - DISABLED example: ACTIVE desc: type: string description: Operator-facing description. example: Summarizes release status and creates operator updates. ownerId: type: string description: Owning user or group id. example: 22222222-2222-4222-8222-222222222222 ownerType: type: string description: Owner type, typically USER or GROUP. example: USER serviceAccountUserId: type: string description: Service account user id used as execution principal. example: 11111111-1111-4111-8111-111111111111 rootStorageEntryId: type: string description: Agent workspace root storage entry id. example: 33333333-3333-4333-8333-333333333333 config: type: object description: Persisted agent runtime defaults and identity inputs. example: model: configured-model maxTicks: 24 policy: type: object description: Persisted execution constraints and role gates. example: maxTicks: 24 toolNames: - ref_search metadata: type: object description: Resource metadata. example: team: operations avatar: type: string description: Signed avatar URL, when an avatar is configured. example: https://storage.example/avatar.png summary: description: >- Per-agent operational summary when requested by list or overview endpoints. example: activeRunCount: 1 queuedInboxCount: 3 allOf: - $ref: '#/components/schemas/AgentSummaryDto' createdBy: type: string description: User id that created the agent. example: 44444444-4444-4444-8444-444444444444 createdAt: format: date-time type: string description: Creation timestamp. example: '2026-06-13T10:00:00.000Z' lastUpdateAt: format: date-time type: string description: Last update timestamp. example: '2026-06-13T10:15:00.000Z' lastUpdateBy: type: string description: User id that last updated the agent. example: 44444444-4444-4444-8444-444444444444 version: type: number description: Optimistic locking version. example: 3 required: - agentId - name - status - serviceAccountUserId - config - policy - createdBy - createdAt - lastUpdateAt - lastUpdateBy - version AgentSummaryDto: type: object properties: activeRunCount: type: number description: Number of active root runs. example: 1 queuedInboxCount: type: number description: Number of PENDING inbox items. example: 3 attachedPluginCount: type: number description: Number of attached registry or inline plugin references. example: 2 totalRunCount: type: number description: Total run count for this agent. example: 14 failedRunCount: type: number description: ERROR run count for this agent. example: 2 blockedRunCount: type: number description: ACTION_REQUIRED run count for this agent. example: 1 tokenUsage: description: >- Token usage aggregated from provider-bearing assistant messages linked to this agent. example: today: 1800 currentBillingPeriod: 28000 previousBillingPeriod: 24000 allTime: 84000 input: 61000 output: 17000 cachedInput: 12000 reasoning: 6000 threadCount: 12 allOf: - $ref: '#/components/schemas/AgentTokenUsageDto' tokenUsageByModel: description: >- All-time provider usage grouped by the model persisted on each assistant message. example: - model: configured-model input: 61000 uncachedInput: 49000 cachedInput: 12000 output: 17000 reasoning: 6000 billable: 67200 type: array items: $ref: '#/components/schemas/AgentTokenUsageByModelDto' tokenUsageSeries: description: Daily token usage for the most recent 30 UTC days. example: - period: '2026-07-13' input: 1200 output: 480 cachedInput: 300 reasoning: 120 toolTokens: 220 billable: 1530 type: array items: $ref: '#/components/schemas/AgentTokenUsagePointDto' taskActivitySeries: description: Daily root-run activity for the most recent 30 UTC days. example: - period: '2026-07-13' created: 0 queued: 1 running: 1 waiting: 0 success: 8 blocked: 1 failure: 2 cancelled: 1 total: 14 type: array items: $ref: '#/components/schemas/AgentTaskActivityPointDto' lastRun: description: Most recent run. example: agentRunId: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa status: FINISHED allOf: - $ref: '#/components/schemas/AgentRunPublicDto' lastFailure: description: Most recent failed run. example: agentRunId: bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb status: ERROR allOf: - $ref: '#/components/schemas/AgentRunPublicDto' lastBlocked: description: Most recent action-required run. example: agentRunId: cccccccc-cccc-4ccc-8ccc-cccccccccccc status: ACTION_REQUIRED allOf: - $ref: '#/components/schemas/AgentRunPublicDto' required: - activeRunCount - queuedInboxCount - attachedPluginCount - totalRunCount - failedRunCount - blockedRunCount - tokenUsage - tokenUsageByModel - tokenUsageSeries - taskActivitySeries AgentTokenUsageDto: type: object properties: today: type: number description: Billed tokens since UTC midnight. example: 1800 currentBillingPeriod: type: number description: Billed tokens in the current UTC calendar month. example: 28000 previousBillingPeriod: type: number description: Billed tokens in the previous UTC calendar month. example: 24000 allTime: type: number description: All billed tokens across linked threads. example: 84000 input: type: number description: Total input tokens across linked threads. example: 61000 output: type: number description: Total output tokens across linked threads. example: 17000 cachedInput: type: number description: Cached input tokens across linked threads. example: 12000 reasoning: type: number description: Reasoning tokens across linked threads. example: 6000 threadCount: type: number description: Number of distinct assistant threads included. example: 12 required: - today - currentBillingPeriod - previousBillingPeriod - allTime - input - output - cachedInput - reasoning - threadCount AgentTokenUsageByModelDto: type: object properties: model: type: string description: Execution model identifier used to group this usage. input: type: number description: Provider input tokens attributed to this model. example: 61000 uncachedInput: type: number description: Non-cached provider input tokens attributed to this model. example: 49000 cachedInput: type: number description: Cached provider input tokens attributed to this model. example: 12000 output: type: number description: Provider output tokens attributed to this model. example: 17000 reasoning: type: number description: Provider reasoning tokens attributed to this model. example: 6000 billable: type: number description: Billing-weighted provider tokens attributed to this model. example: 67200 required: - model - input - uncachedInput - cachedInput - output - reasoning - billable AgentTokenUsagePointDto: type: object properties: period: type: string description: UTC calendar day represented by this point. example: '2026-07-13' input: type: number description: Provider input tokens recorded on this day. example: 1200 output: type: number description: Provider output tokens recorded on this day. example: 480 cachedInput: type: number description: Cached input tokens included in input. example: 300 reasoning: type: number description: Reasoning tokens recorded on this day. example: 120 toolTokens: type: number description: Content tokens emitted by tool messages on this day. example: 220 billable: type: number description: Billing-weighted provider tokens for this day. example: 1530 required: - period - input - output - cachedInput - reasoning - toolTokens - billable AgentTaskActivityPointDto: type: object properties: period: type: string description: UTC calendar day represented by this point. example: '2026-07-13' created: type: number description: Root runs still in CREATED on this day. example: 1 queued: type: number description: >- Compatibility bucket for PENDING root runs that are not waiting on CHILDREN. example: 2 running: type: number description: Compatibility bucket for PROCESSING root runs. example: 1 waiting: type: number description: Compatibility bucket for PENDING root runs waiting on CHILDREN. example: 1 success: type: number description: Compatibility bucket for FINISHED root runs. example: 8 blocked: type: number description: Compatibility bucket for ACTION_REQUIRED root runs. example: 1 failure: type: number description: Compatibility bucket for ERROR root runs. example: 2 cancelled: type: number description: Root runs cancelled on this day. example: 1 total: type: number description: All root runs created on this day. example: 11 required: - period - created - queued - running - waiting - success - blocked - failure - cancelled - total AgentRunPublicDto: type: object properties: agentRunId: type: string description: Stable run id. example: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa agentId: type: string description: Owning agent id. example: 99999999-9999-4999-8999-999999999999 agentSessionId: type: string description: Durable session shared by successor runs. example: abababab-abab-4bab-8bab-abababababab previousRunId: type: string description: Immediately preceding run in this session. example: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa rootRunId: type: string description: Root run id for lineage. example: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa parentRunId: type: string description: Parent run id for delegated child runs. example: bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb status: type: string description: Current run status. enum: - CREATED - PENDING - PROCESSING - ACTION_REQUIRED - FINISHED - ERROR - CANCELLED example: PROCESSING waitReason: type: string description: Reason a run is waiting. enum: - NONE - CHILDREN - CAPACITY - SCHEDULE - RECONCILE example: CHILDREN triggerType: type: string description: Trigger type such as REQUEST, INBOX, SCHEDULE, EVENT, or RETRY. example: REQUEST triggerRefType: type: string description: External trigger reference type. example: scheduleId triggerRefId: type: string description: External trigger reference id. example: schedule-123 ownerId: type: string description: Owning user or group id. example: 22222222-2222-4222-8222-222222222222 ownerType: type: string description: Owner type, typically USER or GROUP. example: USER serviceAccountUserId: type: string description: Service account execution principal. example: 11111111-1111-4111-8111-111111111111 rootAssistantThreadId: type: string description: Root assistant thread for the run. example: cccccccc-cccc-4ccc-8ccc-cccccccccccc currentAssistantThreadId: type: string description: Current assistant thread for the run. example: dddddddd-dddd-4ddd-8ddd-dddddddddddd lastAssistantMessageId: type: string description: Last assistant message id. example: eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee nextWakeAt: format: date-time type: string description: Next scheduled wake timestamp. example: '2026-06-13T10:30:00.000Z' tickSeq: type: number description: Current tick sequence. example: 3 tickCount: type: number description: Number of ticks executed. example: 2 childCount: type: number description: Number of child runs created. example: 1 lastHeartbeatAt: format: date-time type: string description: Last heartbeat timestamp. example: '2026-06-13T10:20:00.000Z' checkpointSummary: type: string description: Bounded terminal or checkpoint summary. example: Run completed and wrote the release summary. state: type: object description: Run-scoped state for operator diagnostics. example: instruction: Review deployment result: type: object description: Terminal result payload. example: summary: Deployment looks healthy. error: type: object description: Terminal error payload. example: message: Run failed. createdAt: format: date-time type: string description: Creation timestamp. example: '2026-06-13T10:00:00.000Z' lastUpdateAt: format: date-time type: string description: Last update timestamp. example: '2026-06-13T10:15:00.000Z' version: type: number description: Optimistic locking version. example: 1 required: - agentRunId - agentId - agentSessionId - status - serviceAccountUserId - tickSeq - tickCount - childCount - state - createdAt - lastUpdateAt - version securitySchemes: bearer: scheme: bearer bearerFormat: JWT description: Bearer JWT token or API Key (sk-*). type: http ````