> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siro.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get evaluated scorecard instance
> Get an evaluated scorecard instance with computed metrics and scores for a specific time period and filter criteria. The user must have access to the organization that owns the scorecard instance.
## What this returns
A fully evaluated scorecard for one rep, team, organization, or recording over a date range — the overall score, every section and metric in the configured tree with raw values plus color-coded points, the rubric and weights used to compute them, and (for `filterBy=USER`) AI-generated coaching spotlights with timestamped citations.
## Where the `{id}` comes from
The `{id}` in the URL is a **scorecard instance id**, not a recording id. To find it, call [Get scorecard instances](/api-references/get-scorecard-instances) for your organization and conversation type. Most orgs have one active instance per conversation type.
If you instead want raw metric values for a single recording (without running a saved scorecard configuration), use [Get scorecard metric values](/api-references/get-scorecard-metrics-values) with `filterBy=RECORDING`. See the [overview](/scorecards-metrics-for-recording) for guidance on when to pick which.
## Picking `filterBy` and `filterByIds`
| `filterBy` | What `filterByIds` should be | Typical use |
| -------------- | ------------------------------------------ | ------------------------------------------------------------------------- |
| `RECORDING` | One or more recording ids | Score a specific call against the saved scorecard |
| `USER` | A Siro user id | Rep-level rollup across the date range; also returns `spotlightSummaries` |
| `TEAM` | A team id | Team-level rollup |
| `ORGANIZATION` | The org id (must match the instance's org) | Org-wide rollup |
## Auth scoping
The caller's `x-siro-auth-token` must belong to the organization that owns the instance, **or** the caller must be a Siro/org/group admin. Non-admins requesting `filterBy=TEAM` must be a member or coach of that team; non-admins requesting `filterBy=USER` must be that user or coach the user's team.
## OpenAPI
````yaml specs/openapi-internalApi.json get /v1/core/scorecards/evaluated-instances/{id}
openapi: 3.0.0
info:
version: 1.0.0
title: Swagger API
servers:
- url: https://api.siro.ai/
description: Siro API Gateway
security: []
externalDocs:
description: View the raw OpenAPI Specification in JSON format
url: /swagger.json
paths:
/v1/core/scorecards/evaluated-instances/{id}:
get:
summary: Get evaluated scorecard instance
description: >-
Get an evaluated scorecard instance with computed metrics and scores for
a specific time period and filter criteria. The user must have access to
the organization that owns the scorecard instance.
parameters:
- schema:
type: string
required: true
name: id
in: path
- schema:
type: string
description: Start date for the evaluation range (ISO 8601 format)
example: '2024-01-01T00:00:00Z'
required: true
description: Start date for the evaluation range (ISO 8601 format)
name: startAt
in: query
- schema:
type: string
description: End date for the evaluation range (ISO 8601 format)
example: '2024-01-31T23:59:59Z'
required: true
description: End date for the evaluation range (ISO 8601 format)
name: endAt
in: query
- schema:
anyOf:
- type: array
items:
type: string
minItems: 1
- type: string
minLength: 1
description: IDs to filter by (can be array or single string)
example:
- recording_001
- recording_002
required: true
description: IDs to filter by (can be array or single string)
name: filterByIds
in: query
- schema:
anyOf:
- type: array
items:
type: string
enum:
- RECORDING
- USER
- TEAM
- ORGANIZATION
description: The entity type to filter scorecard metrics by
example: USER
minItems: 1
- type: string
enum:
- RECORDING
- USER
- TEAM
- ORGANIZATION
description: The entity type to filter scorecard metrics by
example: USER
description: Entity type to filter by (RECORDING, USER, TEAM, ORGANIZATION)
example: RECORDING
required: true
description: Entity type to filter by (RECORDING, USER, TEAM, ORGANIZATION)
name: filterBy
in: query
- schema:
anyOf:
- type: array
items:
type: string
enum:
- RECORDING
- USER
- TEAM
- ORGANIZATION
description: The entity type to filter scorecard metrics by
example: USER
minItems: 1
- type: string
enum:
- RECORDING
- USER
- TEAM
- ORGANIZATION
description: The entity type to filter scorecard metrics by
example: USER
description: Optional grouping for the evaluation results
example: USER
required: false
description: Optional grouping for the evaluation results
name: groupBy
in: query
responses:
'200':
description: Get evaluated scorecard instance
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: ID of the scorecard template or instance
example: scorecard_001
name:
type: string
description: Name of the scorecard
example: Sales Performance Scorecard
description:
type: string
description: Optional description of the scorecard
example: Comprehensive evaluation of sales call performance
recordingsEvaluatedCount:
type: number
description: Number of recordings that were evaluated
example: 150
recordingsWonCount:
type: number
description: Number of recordings that resulted in wins
example: 45
pointsPossible:
type: number
description: Total possible points across all metrics (always 100
example: 100
pointsEarned:
type: number
description: Total points earned across all metrics
example: 75
tags:
type: array
items:
type: string
description: Optional tags for categorization
example:
- sales
- performance
- q1
evaluatedNodes:
type: array
items:
type: object
properties:
id:
type: string
description: Unique identifier for the node
example: node_001
name:
type: string
description: Display name for the node
example: Conversation Quality
description:
type: string
nullable: true
description: Optional description of the node
example: >-
Metrics related to conversation quality and
engagement
indexNumber:
type: number
description: Order of this node within its parent
example: 1
parentId:
type: string
description: ID of the parent node (empty string for root)
example: root
nodeType:
type: string
enum:
- METRIC
- SECTION
- ROOT
description: Type of node (METRIC, SECTION, or ROOT)
example: SECTION
metadata:
anyOf:
- type: object
properties:
metricId:
type: string
description: >-
ID of the metric configuration this node
represents
example: metric_001
metricType:
type: string
enum:
- RECORDING_COUNT
- BOOKMARK
- CONVERSATION_TIME
- REP_SPEAKING_TIME
- CUSTOMER_SPEAKING_TIME
- CUSTOMER_QUESTIONS_COUNT
- REP_QUESTIONS_COUNT
- EXCHANGES_COUNT
- REP_EXCHANGES_COUNT
- TOTAL_REP_EXCHANGES_WITH_A_QUESTION
- REP_WORD_COUNT
- REP_UNIQUE_WORDS_USED_COUNT
- REP_FILLER_WORDS_COUNT
- TOTAL_REP_VOCABULARY_SCORE
- TOTAL_REP_WORD_OBSCURITY_SCORE
- LONGEST_MONOLOGUE_SECONDS
- LONGEST_CUSTOMER_STORY_SECONDS
- REP_WORDS_PER_MINUTE
- REP_FILLER_WORDS_PER_MIN
- REP_SPEAKER_SHARE
- INTERACTIVITY_SCORE
- REP_CONTROL
- REP_VOCABULARY_LEVEL
- REP_WORD_OBSCURITY_SCORE
- AI_METRIC
description: The type of metric this node represents
example: CONVERSATION_TIME
required:
- metricId
- metricType
description: Metadata for a metric node in a scorecard
- type: object
properties:
metricId:
type: string
description: >-
ID of the metric configuration this node
represents
example: metric_001
metricType:
type: string
enum:
- RECORDING_COUNT
- BOOKMARK
- CONVERSATION_TIME
- REP_SPEAKING_TIME
- CUSTOMER_SPEAKING_TIME
- CUSTOMER_QUESTIONS_COUNT
- REP_QUESTIONS_COUNT
- EXCHANGES_COUNT
- REP_EXCHANGES_COUNT
- TOTAL_REP_EXCHANGES_WITH_A_QUESTION
- REP_WORD_COUNT
- REP_UNIQUE_WORDS_USED_COUNT
- REP_FILLER_WORDS_COUNT
- TOTAL_REP_VOCABULARY_SCORE
- TOTAL_REP_WORD_OBSCURITY_SCORE
- LONGEST_MONOLOGUE_SECONDS
- LONGEST_CUSTOMER_STORY_SECONDS
- REP_WORDS_PER_MINUTE
- REP_FILLER_WORDS_PER_MIN
- REP_SPEAKER_SHARE
- INTERACTIVITY_SCORE
- REP_CONTROL
- REP_VOCABULARY_LEVEL
- REP_WORD_OBSCURITY_SCORE
- AI_METRIC
description: The type of metric this node represents
example: CONVERSATION_TIME
bookmarkConfigId:
type: string
description: >-
ID of the bookmark configuration this
metric is based on
example: bookmark_config_001
required:
- metricId
- metricType
- bookmarkConfigId
description: >-
Metadata for a bookmark-based metric node in
a scorecard
- type: object
properties:
metricId:
type: string
description: >-
ID of the metric configuration this node
represents
example: metric_001
metricType:
type: string
enum:
- RECORDING_COUNT
- BOOKMARK
- CONVERSATION_TIME
- REP_SPEAKING_TIME
- CUSTOMER_SPEAKING_TIME
- CUSTOMER_QUESTIONS_COUNT
- REP_QUESTIONS_COUNT
- EXCHANGES_COUNT
- REP_EXCHANGES_COUNT
- TOTAL_REP_EXCHANGES_WITH_A_QUESTION
- REP_WORD_COUNT
- REP_UNIQUE_WORDS_USED_COUNT
- REP_FILLER_WORDS_COUNT
- TOTAL_REP_VOCABULARY_SCORE
- TOTAL_REP_WORD_OBSCURITY_SCORE
- LONGEST_MONOLOGUE_SECONDS
- LONGEST_CUSTOMER_STORY_SECONDS
- REP_WORDS_PER_MINUTE
- REP_FILLER_WORDS_PER_MIN
- REP_SPEAKER_SHARE
- INTERACTIVITY_SCORE
- REP_CONTROL
- REP_VOCABULARY_LEVEL
- REP_WORD_OBSCURITY_SCORE
- AI_METRIC
description: The type of metric this node represents
example: CONVERSATION_TIME
score:
type: string
description: AI-generated score for the metric
example: 85/100
impact:
type: string
description: >-
AI assessment of the metric's impact on
overall performance
example: >-
High impact - this metric significantly
affects customer engagement
thinking:
type: string
description: >-
AI reasoning behind the score and
assessment
example: >-
The rep does a good job of asking
questions and engaging the customer.
recommendation:
type: string
description: >-
AI-generated recommendation for
improvement
example: >-
Consider adding even more discovery
questions to better understand customer
needs
thinkingWithCitation:
type: object
properties:
citedThinking:
type: string
citations:
type: array
items:
type: object
properties:
quote:
type: string
startTimeInMillis:
type: number
endTimeInMillis:
type: number
required:
- quote
- startTimeInMillis
- endTimeInMillis
required:
- citedThinking
- citations
description: >-
AI reasoning behind the score and
assessment with citations
example:
citedThinking: >-
The rep does a good job of asking
questions and engaging the customer. [1]
citations:
- quote: >-
How long have you had problems with your
current provider?
startTimeInMillis: 10000
endTimeInMillis: 12000
required:
- metricId
- metricType
- score
- impact
- thinking
- recommendation
description: >-
Metadata for an AI-generated metric node in
a scorecard
- type: object
properties:
sectionWeight:
type: number
description: >-
Weight of this section relative to other
sections (0-100)
example: 25
required:
- sectionWeight
description: Metadata for a section node in a scorecard
- type: object
properties: {}
description: >-
Metadata for the root node of a scorecard
(no additional properties)
description: Metadata specific to the node type
metricValue:
type: number
nullable: true
description: The calculated value for this metric
example: 85
pointsPossible:
type: number
description: Maximum points possible for this node
example: 100
pointsEarned:
type: number
description: Points earned based on the metric value
example: 75
color:
type: string
enum:
- GREEN
- YELLOW
- RED
description: >-
Color indicating performance level (RED, YELLOW,
GREEN)
example: GREEN
unit:
type: string
nullable: true
description: Full unit name for the metric value
example: seconds
unitAbbreviated:
type: string
description: Abbreviated unit name for the metric value
example: sec
required:
- id
- name
- indexNumber
- parentId
- nodeType
- metadata
- pointsPossible
- pointsEarned
- color
description: A scorecard node with evaluation results
description: Array of evaluated nodes with scores and colors
metricRubrics:
type: array
items:
type: object
properties:
scorecardNodeId:
type: string
description: ID of the scorecard node this rubric applies to
example: node_001
scorecardMetricId:
type: string
description: ID of the metric this rubric evaluates
example: metric_001
metricPointTotal:
type: number
default: 100
description: Maximum points possible for this metric
example: 100
minTarget:
type: number
default: 0
description: Minimum target value for this metric
example: 0
maxTarget:
type: number
default: 0
description: Maximum target value for this metric
example: 100
targetTolerance:
type: number
default: 0
description: Tolerance range around the target values
example: 5
required:
- scorecardNodeId
- scorecardMetricId
description: >-
Rubric defining how a metric should be evaluated and
scored
description: Array of metric rubrics used for evaluation
sectionWeights:
type: array
items:
type: object
properties:
scorecardNodeId:
type: string
description: ID of the scorecard node this weight applies to
example: node_001
weight:
type: number
minimum: 0
maximum: 100
description: Weight percentage for this section (0-100)
example: 25
required:
- scorecardNodeId
- weight
description: Weight configuration for a scorecard section
description: Array of section weights used for scoring
colorConfigurations:
type: array
items:
type: object
properties:
color:
type: string
enum:
- GREEN
- YELLOW
- RED
description: Color indicating performance level
example: GREEN
lowRange:
type: number
description: Lower bound of the range for this color
example: 80
highRange:
type: number
description: Upper bound of the range for this color
example: 100
required:
- color
- lowRange
- highRange
description: Color configuration for a performance range
description: Array of color configurations for performance levels
filterByIds:
anyOf:
- type: array
items:
type: string
minItems: 1
- type: string
minLength: 1
description: IDs that were used for filtering
example:
- user_001
- user_002
filterBy:
anyOf:
- type: array
items:
type: string
enum:
- RECORDING
- USER
- TEAM
- ORGANIZATION
description: The entity type to filter scorecard metrics by
example: USER
minItems: 1
- type: string
enum:
- RECORDING
- USER
- TEAM
- ORGANIZATION
description: The entity type to filter scorecard metrics by
example: USER
description: Entity type that was used for filtering
example: USER
startAt:
type: string
description: Start date of the evaluation range (ISO 8601 format)
example: '2024-01-01T00:00:00Z'
endAt:
type: string
description: End date of the evaluation range (ISO 8601 format)
example: '2024-01-31T23:59:59Z'
spotlightSummaries:
type: array
items:
type: object
properties:
spotlightType:
type: string
enum:
- strength
- weakness
description: strength or weakness
summary:
type: string
description: Summary of the spotlight
title:
type: string
description: Title of the spotlight
score:
type: number
description: >-
The rep's average score for the metric for the
spotlight
recordings:
type: array
items:
type: object
properties:
id:
type: string
dateCreated:
type: string
description: Date the recording was created
score:
type: number
description: >-
The rep's score for the metric for the
spotlight
startTimeInMillis:
type: number
description: Start time of the quote
endTimeInMillis:
type: number
description: End time of the quote
quote:
type: string
description: Quote from the recording
title:
type: string
description: Title of the recording
required:
- id
- dateCreated
- score
- startTimeInMillis
- endTimeInMillis
- quote
- title
required:
- spotlightType
- summary
- title
- score
- recordings
description: >-
Spotlight summaries for the rep for the given
scorecard instance
required:
- id
- name
- recordingsEvaluatedCount
- recordingsWonCount
- pointsPossible
- pointsEarned
- evaluatedNodes
- metricRubrics
- sectionWeights
- colorConfigurations
- filterByIds
- filterBy
- startAt
- endAt
cursor:
anyOf:
- type: string
- type: number
- nullable: true
pageSize:
type: number
limit:
type: number
total:
type: number
nullable: true
hasNextPage:
type: boolean
required:
- data
'400':
description: Bad Request - Invalid parameters
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Error message
required:
- error
'401':
description: Unauthorized - User not authenticated
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Authentication error message
required:
- error
'403':
description: Forbidden - User does not have access
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Authorization error message
required:
- error
'404':
description: Not Found - Resource not found
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Resource not found error message
required:
- error
'422':
description: Unprocessable Content - The request failed validation checks
content:
application/json:
schema:
type: object
properties:
issues:
type: array
items:
type: object
properties:
code:
type: string
expected:
type: string
received:
type: string
path:
type: array
items:
anyOf:
- type: string
- type: number
message:
type: string
required:
- code
- path
- message
name:
type: string
enum:
- ZodError
required:
- issues
- name
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Internal server error message
required:
- error
security:
- SiroAuthToken: []
components:
securitySchemes:
SiroAuthToken:
type: apiKey
in: header
name: x-siro-auth-token
description: >-
OAuth access token for user-scoped requests (Authorization Code or
machine-to-machine). Send header `x-siro-auth-token:
`. Not an organization API key.
x-default:
````