Agno Sessions API
The Sessions API from Agno — 5 operation(s) for sessions.
OpenAPI Specification
openapi: 3.1.0
info:
title: Agno API Reference A2A Sessions API
description: The all-in-one, private, secure agent platform that runs in your cloud.
version: 2.5.6
tags:
- name: Sessions
paths:
/sessions:
get:
tags:
- Sessions
summary: List Sessions
description: Retrieve paginated list of sessions with filtering and sorting options. Supports filtering by session type (agent, team, workflow), component, user, and name. Sessions represent conversation histories and execution contexts.
operationId: get_sessions
security:
- HTTPBearer: []
parameters:
- name: type
in: query
required: false
schema:
$ref: '#/components/schemas/SessionType'
description: Type of sessions to retrieve (agent, team, or workflow)
default: agent
description: Type of sessions to retrieve (agent, team, or workflow)
- name: component_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter sessions by component ID (agent/team/workflow ID)
title: Component Id
description: Filter sessions by component ID (agent/team/workflow ID)
- name: user_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter sessions by user ID
title: User Id
description: Filter sessions by user ID
- name: session_name
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Filter sessions by name (partial match)
title: Session Name
description: Filter sessions by name (partial match)
- name: limit
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 1
- type: 'null'
description: Number of sessions to return per page
default: 20
title: Limit
description: Number of sessions to return per page
- name: page
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 0
- type: 'null'
description: Page number for pagination
default: 1
title: Page
description: Page number for pagination
- name: sort_by
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Field to sort sessions by
default: created_at
title: Sort By
description: Field to sort sessions by
- name: sort_order
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/SortOrder'
- type: 'null'
description: Sort order (asc or desc)
default: desc
title: Sort Order
description: Sort order (asc or desc)
- name: db_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Database ID to query sessions from
title: Db Id
description: Database ID to query sessions from
- name: table
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: The database table to use
title: Table
description: The database table to use
responses:
'200':
description: Sessions retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedResponse_SessionSchema_'
example:
session_example:
summary: Example session response
value:
data:
- session_id: 6f6cfbfd-9643-479a-ae47-b8f32eb4d710
session_name: What tools do you have?
session_state: {}
created_at: '2025-09-05T16:02:09Z'
updated_at: '2025-09-05T16:02:09Z'
'400':
description: Invalid session type or filter parameters
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthenticatedResponse'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
'422':
description: Validation error in query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
post:
tags:
- Sessions
summary: Create New Session
description: Create a new empty session with optional configuration. Useful for pre-creating sessions with specific session_state, metadata, or other properties before running any agent/team/workflow interactions. The session can later be used by providing its session_id in run requests.
operationId: create_session
security:
- HTTPBearer: []
parameters:
- name: type
in: query
required: false
schema:
$ref: '#/components/schemas/SessionType'
description: Type of session to create (agent, team, or workflow)
default: agent
description: Type of session to create (agent, team, or workflow)
- name: db_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Database ID to create session in
title: Db Id
description: Database ID to create session in
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSessionRequest'
description: Session configuration data
default: {}
responses:
'201':
description: Session created successfully
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/AgentSessionDetailSchema'
- $ref: '#/components/schemas/TeamSessionDetailSchema'
- $ref: '#/components/schemas/WorkflowSessionDetailSchema'
title: Response Create Session
examples:
agent_session_example:
summary: Example created agent session
value:
user_id: user-123
agent_session_id: new-session-id
session_id: new-session-id
session_name: New Session
session_state:
key: value
metadata:
key: value
agent_id: agent-1
created_at: '2025-10-21T12:00:00Z'
updated_at: '2025-10-21T12:00:00Z'
'400':
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthenticatedResponse'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
'500':
description: Failed to create session
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
delete:
tags:
- Sessions
summary: Delete Multiple Sessions
description: Delete multiple sessions by their IDs in a single operation. This action cannot be undone and will permanently remove all specified sessions and their runs.
operationId: delete_sessions
security:
- HTTPBearer: []
parameters:
- name: user_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: User ID to scope deletion to
title: User Id
description: User ID to scope deletion to
- name: db_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Database ID to use for deletion
title: Db Id
description: Database ID to use for deletion
- name: table
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Table to use for deletion
title: Table
description: Table to use for deletion
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteSessionRequest'
responses:
'204':
description: Sessions deleted successfully
'400':
description: Invalid request - session IDs and types length mismatch
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthenticatedResponse'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
'500':
description: Failed to delete sessions
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
/sessions/{session_id}:
get:
tags:
- Sessions
summary: Get Session by ID
description: Retrieve detailed information about a specific session including metadata, configuration, and run history. Response schema varies based on session type (agent, team, or workflow).
operationId: get_session_by_id
security:
- HTTPBearer: []
parameters:
- name: session_id
in: path
required: true
schema:
type: string
description: Session ID to retrieve
title: Session Id
description: Session ID to retrieve
- name: type
in: query
required: false
schema:
$ref: '#/components/schemas/SessionType'
description: Session type (agent, team, or workflow)
default: agent
description: Session type (agent, team, or workflow)
- name: user_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: User ID to query session from
title: User Id
description: User ID to query session from
- name: db_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Database ID to query session from
title: Db Id
description: Database ID to query session from
- name: table
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Table to query session from
title: Table
description: Table to query session from
responses:
'200':
description: Session details retrieved successfully
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/AgentSessionDetailSchema'
- $ref: '#/components/schemas/TeamSessionDetailSchema'
- $ref: '#/components/schemas/WorkflowSessionDetailSchema'
title: Response Get Session By Id
examples:
agent_session_example:
summary: Example agent session response
value:
user_id: '123'
agent_session_id: 6f6cfbfd-9643-479a-ae47-b8f32eb4d710
session_id: 6f6cfbfd-9643-479a-ae47-b8f32eb4d710
session_name: What tools do you have?
session_summary:
summary: The user and assistant engaged in a conversation about the tools the agent has available.
updated_at: '2025-09-05T18:02:12.269392'
session_state: {}
agent_id: basic-agent
total_tokens: 160
agent_data:
name: Basic Agent
agent_id: basic-agent
model:
provider: OpenAI
name: OpenAIChat
id: gpt-4o
metrics:
input_tokens: 134
output_tokens: 26
total_tokens: 160
audio_input_tokens: 0
audio_output_tokens: 0
audio_total_tokens: 0
cache_read_tokens: 0
cache_write_tokens: 0
reasoning_tokens: 0
chat_history:
- content: '<additional_information>
- Use markdown to format your answers.
- The current time is 2025-09-05 18:02:09.171627.
</additional_information>
You have access to memories from previous interactions with the user that you can use:
<memories_from_previous_interactions>
- User really likes Digimon and Japan.
- User really likes Japan.
- User likes coffee.
</memories_from_previous_interactions>
Note: this information is from previous interactions and may be updated in this conversation. You should always prefer information from this conversation over the past memories.'
from_history: false
stop_after_tool_call: false
role: system
created_at: 1757088129
- content: What tools do you have?
from_history: false
stop_after_tool_call: false
role: user
created_at: 1757088129
- content: I don't have access to external tools or the internet. However, I can assist you with a wide range of topics by providing information, answering questions, and offering suggestions based on the knowledge I've been trained on. If there's anything specific you need help with, feel free to ask!
from_history: false
stop_after_tool_call: false
role: assistant
metrics:
input_tokens: 134
output_tokens: 26
total_tokens: 160
created_at: 1757088129
created_at: '2025-09-05T16:02:09Z'
updated_at: '2025-09-05T16:02:09Z'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthenticatedResponse'
'404':
description: Session not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
'422':
description: Invalid session type
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
delete:
tags:
- Sessions
summary: Delete Session
description: Permanently delete a specific session and all its associated runs. This action cannot be undone and will remove all conversation history.
operationId: delete_session
security:
- HTTPBearer: []
parameters:
- name: session_id
in: path
required: true
schema:
type: string
description: Session ID to delete
title: Session Id
description: Session ID to delete
- name: user_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: User ID to scope deletion to
title: User Id
description: User ID to scope deletion to
- name: db_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Database ID to use for deletion
title: Db Id
description: Database ID to use for deletion
- name: table
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Table to use for deletion
title: Table
description: Table to use for deletion
responses:
'204':
description: Successful Response
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthenticatedResponse'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
'500':
description: Failed to delete session
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
patch:
tags:
- Sessions
summary: Update Session
description: Update session properties such as session_name, session_state, metadata, or summary. Use this endpoint to modify the session name, update state, add metadata, or update the session summary.
operationId: update_session
security:
- HTTPBearer: []
parameters:
- name: session_id
in: path
required: true
schema:
type: string
description: Session ID to update
title: Session Id
description: Session ID to update
- name: type
in: query
required: false
schema:
$ref: '#/components/schemas/SessionType'
description: Session type (agent, team, or workflow)
default: agent
description: Session type (agent, team, or workflow)
- name: user_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: User ID
title: User Id
description: User ID
- name: db_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Database ID to use for update operation
title: Db Id
description: Database ID to use for update operation
- name: table
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Table to use for update operation
title: Table
description: Table to use for update operation
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSessionRequest'
description: Session update data
responses:
'200':
description: Session updated successfully
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/AgentSessionDetailSchema'
- $ref: '#/components/schemas/TeamSessionDetailSchema'
- $ref: '#/components/schemas/WorkflowSessionDetailSchema'
title: Response Update Session
examples:
update_summary:
summary: Update session summary
value:
summary:
summary: The user discussed project planning with the agent.
updated_at: '2025-10-21T14:30:00Z'
update_metadata:
summary: Update session metadata
value:
metadata:
tags:
- planning
- project
priority: high
update_session_name:
summary: Update session name
value:
session_name: Updated Session Name
update_session_state:
summary: Update session state
value:
session_state:
step: completed
context: Project planning finished
progress: 100
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthenticatedResponse'
'404':
description: Session not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
'422':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
'500':
description: Failed to update session
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
/sessions/{session_id}/runs:
get:
tags:
- Sessions
summary: Get Session Runs
description: Retrieve all runs (executions) for a specific session with optional timestamp filtering. Runs represent individual interactions or executions within a session. Response schema varies based on session type.
operationId: get_session_runs
security:
- HTTPBearer: []
parameters:
- name: session_id
in: path
required: true
schema:
type: string
description: Session ID to get runs from
title: Session Id
description: Session ID to get runs from
- name: type
in: query
required: false
schema:
$ref: '#/components/schemas/SessionType'
description: Session type (agent, team, or workflow)
default: agent
description: Session type (agent, team, or workflow)
- name: user_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: User ID to query runs from
title: User Id
description: User ID to query runs from
- name: created_after
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Filter runs created after this Unix timestamp (epoch time in seconds)
title: Created After
description: Filter runs created after this Unix timestamp (epoch time in seconds)
- name: created_before
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Filter runs created before this Unix timestamp (epoch time in seconds)
title: Created Before
description: Filter runs created before this Unix timestamp (epoch time in seconds)
- name: db_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Database ID to query runs from
title: Db Id
description: Database ID to query runs from
- name: table
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Table to query runs from
title: Table
description: Table to query runs from
responses:
'200':
description: Session runs retrieved successfully
content:
application/json:
schema:
type: array
items:
anyOf:
- $ref: '#/components/schemas/RunSchema'
- $ref: '#/components/schemas/TeamRunSchema'
- $ref: '#/components/schemas/WorkflowRunSchema'
title: Response Get Session Runs
examples:
completed_run:
summary: Example completed run
value:
run_id: fcdf50f0-7c32-4593-b2ef-68a558774340
parent_run_id: 80056af0-c7a5-4d69-b6a2-c3eba9f040e0
agent_id: basic-agent
user_id: ''
run_input: Which tools do you have access to?
content: I don't have access to external tools or the internet. However, I can assist you with a wide range of topics by providing information, answering questions, and offering suggestions based on the knowledge I've been trained on. If there's anything specific you need help with, feel free to ask!
run_response_format: text
reasoning_content: ''
metrics:
input_tokens: 82
output_tokens: 56
total_tokens: 138
time_to_first_token: 0.047505500027909875
duration: 4.840060166025069
messages:
- content: '<additional_information>
- Use markdown to format your answers.
- The current time is 2025-09-08 17:52:10.101003.
</additional_information>
You have the capability to retain memories from previous interactions with the user, but have not had any interactions with the user yet.'
from_history: false
stop_after_tool_call: false
role: system
created_at: 1757346730
- content: Which tools do you have access to?
from_history: false
stop_after_tool_call: false
role: user
created_at: 1757346730
- content: I don't have access to external tools or the internet. However, I can assist you with a wide range of topics by providing information, answering questions, and offering suggestions based on the knowledge I've been trained on. If there's anything specific you need help with, feel free to ask!
from_history: false
stop_after_tool_call: false
role: assistant
metrics:
input_tokens: 82
output_tokens: 56
total_tokens: 138
created_at: 1757346730
events:
- created_at: 1757346730
event: RunStarted
agent_id: basic-agent
agent_name: Basic Agent
run_id: fcdf50f0-7c32-4593-b2ef-68a558774340
session_id: 80056af0-c7a5-4d69-b6a2-c3eba9f040e0
model: gpt-4o
model_provider: OpenAI
- created_at: 1757346733
event: MemoryUpdateStarted
agent_id: basic-agent
agent_name: Basic Agent
run_id: fcdf50f0-7c32-4593-b2ef-68a558774340
session_id: 80056af0-c7a5-4d69-b6a2-c3eba9f040e0
- created_at: 1757346734
event: MemoryUpdateCompleted
agent_id: basic-agent
agent_name: Basic Agent
run_id: fcdf50f0-7c32-4593-b2ef-68a558774340
session_id: 80056af0-c7a5-4d69-b6a2-c3eba9f040e0
- created_at: 1757346734
event: RunCompleted
agent_id: basic-agent
agent_name: Basic Agent
run_id: fcdf50f0-7c32-4593-b2ef-68a558774340
session_id: 80056af0-c7a5-4d69-b6a2-c3eba9f040e0
content: I don't have access to external tools or the internet. However, I can assist you with a wide range of topics by providing information, answering questions, and offering suggestions based on the knowledge I've been trained on. If there's anything specific you need help with, feel free to ask!
content_type: str
metrics:
input_tokens: 82
output_tokens: 56
total_tokens: 138
time_to_first_token: 0.047505500027909875
duration: 4.840060166025069
created_at: '2025-09-08T15:52:10Z'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthenticatedResponse'
'404':
description: Session not found or has no runs
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
'422':
description: Invalid session type
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
'500':
description: Internal Server
# --- truncated at 32 KB (73 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/agno/refs/heads/main/openapi/agno-sessions-api-openapi.yml