> ## Documentation Index > Fetch the complete documentation index at: https://docs.cerca.dev/llms.txt > Use this file to discover all available pages before exploring further. # List events ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/cerca/openapi.documented.yml get /agents/{agentId}/events openapi: 3.1.0 info: description: API-key accessible routes for Cerca agents. title: Cerca API version: 0.0.0 servers: - url: https://api.cerca.dev security: - bearerAuth: [] paths: /agents/{agentId}/events: get: tags: - Events summary: List events parameters: - schema: type: string minLength: 1 example: agent_abc123 required: true in: path name: agentId - schema: type: string description: Opaque pagination cursor returned by a previous request. example: cursor_abc123 required: false description: Opaque pagination cursor returned by a previous request. name: cursor in: query - schema: type: string description: Comma-separated event type filter. example: thread.created,thread.completed required: false description: Comma-separated event type filter. name: events in: query - schema: type: string enum: - 'true' - 'false' description: When true, starts from the beginning of the retained buffer. example: 'true' required: false description: When true, starts from the beginning of the retained buffer. name: history in: query - schema: type: string description: >- Maximum number of items to return. Defaults to 20 and preserves parseInt semantics. example: '20' required: false description: >- Maximum number of items to return. Defaults to 20 and preserves parseInt semantics. name: limit in: query responses: '200': description: Agent events page. content: application/json: schema: $ref: '#/components/schemas/EventsPage' '400': description: Invalid runtime request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- Access denied or non-transient quota exceeded. Limit errors include a stable code field. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Runtime resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: >- Transient capacity limit exceeded. Limit errors include a stable code field. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Required runtime dependency unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' default: description: Runtime error response. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] x-codeSamples: - lang: JavaScript source: >- import Cerca from '@cerca-dev/sdk'; const client = new Cerca({ apiKey: process.env['CERCA_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const subscriptionEvent of client.events.listForAgent('agent_abc123')) { console.log(subscriptionEvent.event); } - lang: Python source: |- import os from cerca import Cerca client = Cerca( api_key=os.environ.get("CERCA_API_KEY"), # This is the default and can be omitted ) page = client.events.list_for_agent( agent_id="agent_abc123", ) page = page.events[0] print(page.event) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/matrices/cerca-go\"\n\t\"github.com/matrices/cerca-go/option\"\n)\n\nfunc main() {\n\tclient := cercago.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpage, err := client.Events.ListForAgent(\n\t\tcontext.TODO(),\n\t\t\"agent_abc123\",\n\t\tcercago.EventListForAgentParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n" - lang: Ruby source: |- require "cerca" cerca = Cerca::Client.new(api_key: "My API Key") page = cerca.events.list_for_agent("agent_abc123") puts(page) - lang: CLI source: |- cerca events list-for-agent \ --api-key 'My API Key' \ --agent-id agent_abc123 components: schemas: EventsPage: type: object properties: cursor: type: - string - 'null' events: type: array items: $ref: '#/components/schemas/SubscriptionEvent' hasMore: type: boolean required: - cursor - events - hasMore ErrorResponse: type: object properties: error: type: string code: type: string description: Stable machine-readable error code when the API can provide one. example: MONTHLY_TOKEN_BUDGET_EXCEEDED required: - error SubscriptionEvent: type: object properties: event: $ref: '#/components/schemas/RuntimeWebhookEvent' seq: type: number required: - event - seq RuntimeWebhookEvent: oneOf: - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/AgentCreatedWebhookData' event: type: string enum: - agent.created x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: AgentCreatedWebhookEvent x-stainless-variantName: AgentCreatedWebhookEvent - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/AgentUpdatedWebhookData' event: type: string enum: - agent.updated x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: AgentUpdatedWebhookEvent x-stainless-variantName: AgentUpdatedWebhookEvent - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/AgentDeletedWebhookData' event: type: string enum: - agent.deleted x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: AgentDeletedWebhookEvent x-stainless-variantName: AgentDeletedWebhookEvent - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/ThreadCreatedWebhookData' event: type: string enum: - thread.created x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: ThreadCreatedWebhookEvent x-stainless-variantName: ThreadCreatedWebhookEvent - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/ThreadStatusChangedWebhookData' event: type: string enum: - thread.status.changed x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: ThreadStatusChangedWebhookEvent x-stainless-variantName: ThreadStatusChangedWebhookEvent - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/ThreadCompletedWebhookData' event: type: string enum: - thread.completed x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: ThreadCompletedWebhookEvent x-stainless-variantName: ThreadCompletedWebhookEvent - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/ThreadFailedWebhookData' event: type: string enum: - thread.failed x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: ThreadFailedWebhookEvent x-stainless-variantName: ThreadFailedWebhookEvent - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/TurnCreatedWebhookData' event: type: string enum: - turn.created x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: TurnCreatedWebhookEvent x-stainless-variantName: TurnCreatedWebhookEvent - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/TurnCompletedWebhookData' event: type: string enum: - turn.completed x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: TurnCompletedWebhookEvent x-stainless-variantName: TurnCompletedWebhookEvent - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/TurnFailedWebhookData' event: type: string enum: - turn.failed x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: TurnFailedWebhookEvent x-stainless-variantName: TurnFailedWebhookEvent - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/MessageCreatedWebhookData' event: type: string enum: - message.created x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: MessageCreatedWebhookEvent x-stainless-variantName: MessageCreatedWebhookEvent - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/ApprovalRequestedWebhookData' event: type: string enum: - approval.requested x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: ApprovalRequestedWebhookEvent x-stainless-variantName: ApprovalRequestedWebhookEvent - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/ApprovalResolvedWebhookData' event: type: string enum: - approval.resolved x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: ApprovalResolvedWebhookEvent x-stainless-variantName: ApprovalResolvedWebhookEvent - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/ApprovalGrantedWebhookData' event: type: string enum: - approval.granted x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: ApprovalGrantedWebhookEvent x-stainless-variantName: ApprovalGrantedWebhookEvent - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/ScheduleCreatedWebhookData' event: type: string enum: - schedule.created x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: ScheduleCreatedWebhookEvent x-stainless-variantName: ScheduleCreatedWebhookEvent - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/ScheduleDeletedWebhookData' event: type: string enum: - schedule.deleted x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: ScheduleDeletedWebhookEvent x-stainless-variantName: ScheduleDeletedWebhookEvent - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/ScheduleTriggeredWebhookData' event: type: string enum: - schedule.triggered x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: ScheduleTriggeredWebhookEvent x-stainless-variantName: ScheduleTriggeredWebhookEvent - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/ConnectionAttachedWebhookData' event: type: string enum: - connection.attached x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: ConnectionAttachedWebhookEvent x-stainless-variantName: ConnectionAttachedWebhookEvent - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/ConnectionDetachedWebhookData' event: type: string enum: - connection.detached x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: ConnectionDetachedWebhookEvent x-stainless-variantName: ConnectionDetachedWebhookEvent - type: object properties: agentId: type: string fleetId: type: string id: type: string orgId: type: string threadId: type: - string - 'null' timestamp: type: string data: $ref: '#/components/schemas/WebhookTestWebhookData' event: type: string enum: - webhook.test x-stainless-const: true required: - agentId - fleetId - id - orgId - threadId - timestamp - data - event title: WebhookTestWebhookEvent x-stainless-variantName: WebhookTestWebhookEvent discriminator: propertyName: event AgentCreatedWebhookData: type: object properties: agent: $ref: '#/components/schemas/AgentWebhookPayload' required: - agent AgentUpdatedWebhookData: type: object properties: agent: $ref: '#/components/schemas/AgentWebhookPayload' trigger: type: string enum: - configuration - metadata required: - agent - trigger AgentDeletedWebhookData: type: object properties: agentId: type: string required: - agentId ThreadCreatedWebhookData: type: object properties: message: type: string model: type: string required: - message - model ThreadStatusChangedWebhookData: type: object properties: error: type: - string - 'null' previousStatus: $ref: '#/components/schemas/ThreadStatus' result: type: - string - 'null' status: $ref: '#/components/schemas/ThreadStatus' required: - error - previousStatus - result - status ThreadCompletedWebhookData: type: object properties: previousStatus: $ref: '#/components/schemas/ThreadStatus' result: type: string status: $ref: '#/components/schemas/ThreadStatus' required: - previousStatus - result - status ThreadFailedWebhookData: type: object properties: error: type: string previousStatus: $ref: '#/components/schemas/ThreadStatus' status: $ref: '#/components/schemas/ThreadStatus' required: - error - previousStatus - status TurnCreatedWebhookData: type: object properties: message: type: string seq: type: number startedAt: type: string turnId: type: string required: - message - seq - startedAt - turnId TurnCompletedWebhookData: type: object properties: completedAt: type: string error: type: - string - 'null' result: type: - string - 'null' seq: type: number status: type: string enum: - completed x-stainless-const: true tokenUsage: $ref: '#/components/schemas/TokenUsage' turnId: type: string required: - completedAt - error - result - seq - status - tokenUsage - turnId TurnFailedWebhookData: type: object properties: completedAt: type: string error: type: - string - 'null' result: type: - string - 'null' seq: type: number status: type: string enum: - failed x-stainless-const: true tokenUsage: $ref: '#/components/schemas/TokenUsage' turnId: type: string required: - completedAt - error - result - seq - status - tokenUsage - turnId MessageCreatedWebhookData: type: object properties: createdAt: type: string role: type: string enum: - user - assistant seq: type: number turnId: type: - string - 'null' required: - createdAt - role - seq - turnId ApprovalRequestedWebhookData: type: object properties: approval: $ref: '#/components/schemas/WebhookApprovalRequest' required: - approval ApprovalResolvedWebhookData: type: object properties: approvalId: type: string decision: type: string enum: - approved - denied - timed_out - cancelled required: - approvalId - decision ApprovalGrantedWebhookData: type: object properties: grantId: type: string scope: type: string enum: - thread - agent threadId: type: string toolName: type: string required: - grantId - scope - toolName ScheduleCreatedWebhookData: type: object properties: cron: type: string name: type: string runAt: type: string scheduleId: type: string required: - name - scheduleId ScheduleDeletedWebhookData: type: object properties: scheduleId: type: string required: - scheduleId ScheduleTriggeredWebhookData: type: object properties: scheduleId: type: string threadId: type: string required: - scheduleId - threadId ConnectionAttachedWebhookData: type: object properties: connectionId: type: string provider: type: string required: - connectionId - provider ConnectionDetachedWebhookData: type: object properties: connectionId: type: string provider: type: string required: - connectionId - provider WebhookTestWebhookData: type: object properties: {} additionalProperties: false x-stainless-empty-object: true AgentWebhookPayload: type: object properties: configuration: $ref: '#/components/schemas/AgentConfiguration' createdAt: type: string effective: $ref: '#/components/schemas/EffectiveConfiguration' fleetId: type: string id: type: string metadata: $ref: '#/components/schemas/AgentMetadata' orgId: type: string updatedAt: type: string userId: type: string required: - configuration - createdAt - fleetId - id - metadata - orgId - updatedAt - userId ThreadStatus: type: string enum: - idle - running - awaiting - closed description: >- `idle` threads can accept a new turn or be closed. `running` threads have an active turn. `awaiting` threads are paused on external input such as approvals. `closed` threads are terminal. TokenUsage: type: - object - 'null' properties: inputTokens: type: number outputTokens: type: number required: - inputTokens - outputTokens WebhookApprovalRequest: type: object properties: createdAt: type: string id: type: string input: $ref: '#/components/schemas/WebhookJsonValue' resolvedAt: type: - string - 'null' runtimeToolName: $ref: '#/components/schemas/RuntimeToolName' status: type: string enum: - pending - approved - denied - cancelled - timed_out threadId: type: - string - 'null' timeoutAt: type: - string - 'null' timeoutMs: type: - number - 'null' toolIndex: type: number toolName: type: string toolSourceId: type: string toolSourceVersion: type: number toolUseId: type: string turnId: type: string required: - createdAt - id - input - resolvedAt - runtimeToolName - status - threadId - timeoutAt - timeoutMs - toolIndex - toolName - toolUseId - turnId AgentConfiguration: type: object properties: approvals: $ref: '#/components/schemas/ApprovalPolicy' defaultModel: type: string instructions: type: string tools: type: array items: $ref: '#/components/schemas/RuntimeToolSpec' description: >- Agent tool allowlist. These tools are subject to fleet defaults and locks, and thread or turn requests may only narrow the resulting effective tools. EffectiveConfiguration: type: object properties: approvals: type: object properties: tools: type: object additionalProperties: $ref: '#/components/schemas/RuntimeApprovalPolicyMode' timeoutMs: type: number required: - tools - timeoutMs approvalsWritableByAgent: type: boolean defaultModel: type: string instructions: type: string lockedByFleet: type: array items: $ref: '#/components/schemas/ConfigurationFieldName' resolvedFromFleet: type: array items: $ref: '#/components/schemas/ConfigurationFieldName' tools: type: array items: $ref: '#/components/schemas/RuntimeToolName' description: >- Effective internal runtime tools after applying fleet defaults, fleet locks, and the agent allowlist. required: - approvals - approvalsWritableByAgent - defaultModel - lockedByFleet - resolvedFromFleet - tools AgentMetadata: type: object additionalProperties: type: string description: >- Arbitrary string metadata stored on an agent. Runtime enforces maximum key and value sizes. example: project: alpha WebhookJsonValue: description: JSON value payload. Generated SDKs may expose this as unknown or Any. x-stainless-any: true RuntimeToolName: type: string enum: - get_time - sub_thread - wait - tool.call - tool.discover - artifact.read - agent.threads.list - agent.threads.get - agent.approvals.cancel - agent.approvals.grant_thread - agent.approvals.grant_agent - agent.create - agent.approvals.update - tool.connect - sandbox.exec - sandbox.read - sandbox.write_file - sandbox.read_file - sandbox.spawn - sandbox.stdin - sandbox.session_read - sandbox.kill - sandbox.list_sessions - sandbox.sync_artifact - memory.read - memory.list - memory.search - memory.write - memory.delete - db.query - web.search - web.fetch - agent.schedule.list - agent.schedule.create - agent.schedule.update - agent.schedule.delete - agent.schedule.trigger ApprovalPolicy: type: object properties: tools: type: object additionalProperties: $ref: '#/components/schemas/RuntimeApprovalPolicyMode' timeoutMs: type: number RuntimeToolSpec: type: string minLength: 1 description: >- Configurable runtime tool name, configurable namespace wildcard such as sandbox.*, or external namespace wildcard such as google.*. At thread and turn scope, entries can only narrow the agent's effective tools. examples: - sandbox.* - memory.read - google.* RuntimeApprovalPolicyMode: type: string enum: - always - never ConfigurationFieldName: type: string enum: - defaultModel - instructions - tools - approvals securitySchemes: bearerAuth: bearerFormat: Cerca API key scheme: bearer type: http ````