The Sessions API from Exec — 2 operation(s) for sessions.
openapi: 3.0.3
info:
title: Exec Collections Sessions API
version: '1.0'
description: 'REST API for programmatic access to your Exec workspace.
Use the Exec API to read workspace data, list members, retrieve group information,
and create interactive scenario creation sessions.
## Authentication
All requests require a valid API key passed in the Authorization header:
```
Authorization: Bearer exec_live_...
```
Create API keys in your workspace settings under **Settings > API**.
'
servers:
- url: https://api.exec.com/rest/v1
description: Production
security:
- bearerAuth: []
tags:
- name: Sessions
paths:
/sessions:
get:
operationId: listSessions
summary: List roleplay sessions
description: 'Returns a paginated list of roleplay sessions in the workspace with inline user and scenario data.
Sessions represent individual practice attempts on AI roleplay scenarios. Each session
includes the participant''s score, rank, duration, and metadata. Use filters to narrow
results by user, scenario, skill, program, group, or date range.
Note: Sessions may include users who are no longer active workspace members (e.g., users
who have been removed). These users will not appear in GET /workspace/members but their
historical session data is preserved.
Results are ordered by creation date (newest first) by default.
'
tags:
- Sessions
parameters:
- name: user_ids
in: query
description: Comma-separated user IDs to filter by. When combined with user_emails, results are unioned (all matching users from either list are included).
schema:
type: string
example: u1a2b3c4d5e6,u7v8w9x0y1z2
- name: user_emails
in: query
description: Comma-separated user email addresses to filter by. When combined with user_ids, results are unioned (all matching users from either list are included).
schema:
type: string
example: jane@acme.com,bob@acme.com
- name: scenario_ids
in: query
description: Comma-separated scenario IDs to filter by
schema:
type: string
- name: collection_ids
in: query
description: Comma-separated collection IDs to filter by
schema:
type: string
- name: skill_ids
in: query
description: Comma-separated skill IDs to filter by
schema:
type: string
- name: program_ids
in: query
description: Comma-separated program IDs to filter by
schema:
type: string
- name: group_ids
in: query
description: Comma-separated workspace group IDs to filter by
schema:
type: string
- name: rank
in: query
description: Filter by one or more performance ranks
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- gold
- silver
- bronze
- unranked
example:
- gold
- silver
- name: start_date
in: query
description: ISO 8601 datetime — only include sessions created on or after this date
schema:
type: string
format: date-time
- name: end_date
in: query
description: ISO 8601 datetime — only include sessions created on or before this date
schema:
type: string
format: date-time
- name: exclude_system_users
in: query
description: Exclude sessions from system users (emails ending in @exec.com). Default false.
schema:
type: boolean
default: false
- name: sorting
in: query
description: Sort field. Prefix with `-` for descending order.
schema:
type: string
default: -created_at
enum:
- created_at
- -created_at
- score
- -score
- duration
- -duration
- name: page
in: query
description: Page number (1-indexed)
schema:
type: integer
default: 1
minimum: 1
- name: page_size
in: query
description: Number of results per page (max 100)
schema:
type: integer
default: 50
minimum: 1
maximum: 100
responses:
'200':
description: Paginated list of roleplay sessions
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/SessionListItem'
pagination:
$ref: '#/components/schemas/Pagination'
example:
data:
- id: abc123def456
user:
id: u1a2b3c4d5e6
email: jane@acme.com
first_name: Jane
last_name: Smith
scenario:
id: s1a2b3c4d5e6
name: Procurement Discovery
slug: procurement-discovery
score: 82.5
rank: gold
duration_seconds: 347
is_valid_attempt: true
created_at: '2026-03-15T14:30:00Z'
pagination:
page: 1
page_size: 50
total_count: 128
total_pages: 3
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/sessions/{session_id}:
get:
operationId: getSession
summary: Get session detail
description: 'Returns full detail for a single roleplay session, including score, rank, duration,
and feedback.
Use the `include` parameter to fetch optional heavy fields like the full conversation
transcript or evaluation criteria with grades. These are omitted by default to keep
responses lean.
'
tags:
- Sessions
parameters:
- name: session_id
in: path
required: true
description: The session's unique identifier (UUID)
schema:
type: string
- name: include
in: query
description: 'Comma-separated list of optional sections to include in the response.
Available values: `transcript` (conversation lines), `evaluations` (rubric criteria with grades).
'
schema:
type: string
example: transcript,evaluations
responses:
'200':
description: Session detail
content:
application/json:
schema:
$ref: '#/components/schemas/SessionDetail'
example:
id: abc123def456
user:
id: u1a2b3c4d5e6
email: jane@acme.com
first_name: Jane
last_name: Smith
scenario:
id: s1a2b3c4d5e6
name: Procurement Discovery
slug: procurement-discovery
score: 82.5
rank: gold
duration_seconds: 347
is_valid_attempt: true
outcome_feedback: Strong discovery questioning with good rapport building.
positive_feedback: Excellent use of open-ended questions to uncover needs.
constructive_feedback: Consider probing deeper into budget constraints.
created_at: '2026-03-15T14:30:00Z'
transcript:
- speaker: ai
text: Hi, I'm the procurement lead at Globex. Thanks for meeting with me today.
seconds_from_start: 0
- speaker: user
text: Thanks for your time. I'd love to learn more about your current process.
seconds_from_start: 4.2
evaluations:
- criterion_name: Communication Skills
items:
- name: Discovery Questions
grade: good
feedback: Asked targeted questions about pain points and current workflow.
feedback_examples:
- quote: Tell me about your current procurement process.
feedback: Great open-ended discovery question.
suggestion_quote: null
grade: good
salience: high
- criterion_name: Objection Handling
items:
- name: Budget Concerns
grade: mid
feedback: Addressed the budget concern but could have reframed value more clearly.
feedback_examples: []
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
User:
type: object
properties:
id:
type: string
description: Unique user identifier
email:
type: string
format: email
description: User's email address
first_name:
type: string
description: User's first name
last_name:
type: string
description: User's last name
FeedbackExample:
type: object
description: A specific piece of evidence from the transcript supporting an evaluation.
properties:
quote:
type: string
description: Transcript excerpt
feedback:
type: string
nullable: true
description: Explanation of what was good or could be improved
suggestion_quote:
type: string
nullable: true
description: Suggested alternative phrasing
grade:
type: string
nullable: true
enum:
- good
- mid
- bad
- not_relevant
description: Grade for this specific moment
salience:
type: string
nullable: true
enum:
- high
- mid
- low
description: Importance level of this feedback
ValidationErrorDetail:
type: object
properties:
error:
type: object
properties:
type:
type: string
description: Error category (e.g., "invalid_request")
code:
type: string
description: Specific error code (e.g., "user_not_found")
message:
type: string
description: Human-readable error message
SessionDetail:
type: object
description: Full roleplay session detail with optional transcript and evaluations.
properties:
id:
type: string
description: Unique session identifier
user:
$ref: '#/components/schemas/User'
scenario:
$ref: '#/components/schemas/ScenarioRef'
score:
type: number
nullable: true
description: Session score (0-100 scale)
rank:
type: string
nullable: true
enum:
- gold
- silver
- bronze
- unranked
description: Performance rank based on score
duration_seconds:
type: number
nullable: true
description: Session duration in seconds
is_valid_attempt:
type: boolean
description: Whether this session counts as a valid graded attempt. A session is valid when it was completed (not abandoned), received AI grading, and has a score. Use valid attempts for analytics; non-valid sessions may be incomplete or ungraded.
outcome_feedback:
type: string
nullable: true
description: Overall outcome summary from the AI evaluator
positive_feedback:
type: string
nullable: true
description: What the participant did well
constructive_feedback:
type: string
nullable: true
description: Areas for improvement
transcript:
type: array
nullable: true
description: Conversation transcript lines, excluding system messages (only included when requested via `?include=transcript`)
items:
$ref: '#/components/schemas/TranscriptLine'
evaluations:
type: array
nullable: true
description: Evaluation criteria with grades (only included when requested via `?include=evaluations`)
items:
$ref: '#/components/schemas/EvaluationCriterion'
created_at:
type: string
format: date-time
description: When the session was created
EvaluationCriterion:
type: object
description: A rubric criterion with its evaluated items and feedback examples.
properties:
criterion_name:
type: string
description: Name of the parent evaluation criterion
items:
type: array
description: Evaluated items under this criterion
items:
$ref: '#/components/schemas/EvaluationItem'
SessionListItem:
type: object
description: A roleplay session summary for list responses.
properties:
id:
type: string
description: Unique session identifier
user:
$ref: '#/components/schemas/User'
description: The user who participated in this session
scenario:
$ref: '#/components/schemas/ScenarioRef'
description: The scenario that was practiced
score:
type: number
nullable: true
description: Session score (0-100 scale)
rank:
type: string
nullable: true
enum:
- gold
- silver
- bronze
- unranked
description: Performance rank based on score
duration_seconds:
type: number
nullable: true
description: Session duration in seconds
is_valid_attempt:
type: boolean
description: Whether this session counts as a valid graded attempt. A session is valid when it was completed (not abandoned), received AI grading, and has a score. Use valid attempts for analytics; non-valid sessions may be incomplete or ungraded.
created_at:
type: string
format: date-time
description: When the session was created
EvaluationItem:
type: object
description: An individual evaluation item with grade, feedback, and evidence.
properties:
name:
type: string
description: Name of the evaluation item
grade:
type: string
nullable: true
enum:
- good
- mid
- bad
- not_relevant
description: Grade received on this item
feedback:
type: string
nullable: true
description: Detailed feedback for this item
feedback_examples:
type: array
description: Specific transcript evidence supporting the evaluation (filtered to High/Mid salience)
items:
$ref: '#/components/schemas/FeedbackExample'
Pagination:
type: object
properties:
page:
type: integer
description: Current page number
page_size:
type: integer
description: Number of items per page
total_count:
type: integer
description: Total number of items
total_pages:
type: integer
description: Total number of pages
TranscriptLine:
type: object
description: A single line in the session transcript.
properties:
speaker:
type: string
nullable: true
description: Speaker identifier (e.g. "ai" for the AI character, "user" for the participant)
text:
type: string
description: The spoken text
seconds_from_start:
type: number
nullable: true
description: Seconds elapsed from the start of the session
ScenarioRef:
type: object
description: A compact scenario reference for embedding in other responses.
properties:
id:
type: string
description: Unique scenario identifier
name:
type: string
description: Scenario name
slug:
type: string
description: URL-friendly scenario identifier
responses:
Unauthorized:
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorDetail'
example:
error:
type: authentication_error
code: invalid_api_key
message: Invalid or inactive API key
BadRequest:
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorDetail'
example:
error:
type: invalid_request
code: invalid_pagination
message: Invalid pagination parameters
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorDetail'
example:
error:
type: not_found
message: 'Scenario not found: abc123'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'API key created in Settings > API.
Format: `exec_live_` followed by 40 alphanumeric characters.
'