> ## 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 scorecard instances
> Get scorecard instances for an organization with optional filtering.
## Why you'd call this
This is how you discover the **scorecard instance `id`** you'll pass to [Get evaluated scorecard instance](/api-references/get-evaluated-scorecard-instance). A scorecard instance is the saved configuration (sections, metrics, weights, color thresholds) used to grade a slice of recordings for a given organization and conversation type.
Typical flow:
Call this endpoint with `organizationId` (required) and optionally `conversationTypeId` and `isActive=true`.
Most orgs have one active instance per conversation type. Each item in the response carries an `id`.
Pass that `id` to [Get evaluated scorecard instance](/api-references/get-evaluated-scorecard-instance) along with `startAt`, `endAt`, `filterBy`, and `filterByIds`.
Non-admin callers only see active instances scoped to their own organization and assigned conversation types. Org/group/Siro admins see every instance for the requested org.
## OpenAPI
````yaml specs/openapi-internalApi.json get /v1/core/scorecards/instances
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/instances:
get:
summary: Get scorecard instances
description: Get scorecard instances for an organization with optional filtering.
parameters:
- schema:
type: string
required: false
name: organizationId
in: query
- schema:
type: string
required: false
name: conversationTypeId
in: query
- schema:
type: boolean
nullable: true
required: false
name: isActive
in: query
responses:
'200':
description: Get scorecard instances
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
scorecardInstances:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
nodes:
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
required:
- id
- name
- indexNumber
- parentId
- nodeType
- metadata
description: A scorecard node with type-specific metadata
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
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
metricConfigurations:
type: array
items:
type: object
properties:
id:
type: string
description: >-
Unique identifier for the metric
configuration
example: metric_001
name:
type: string
description: Display name for the metric
example: Conversation Time
description:
type: string
description: >-
Optional description of what the metric
measures
example: >-
Total duration of the conversation in
seconds
unit:
type: string
description: >-
Full unit name (e.g., "seconds",
"percentage")
example: seconds
unitAbbreviated:
type: string
description: Abbreviated unit name (e.g., "sec", "%")
example: sec
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 being configured
example: CONVERSATION_TIME
llmPrompt:
type: string
description: >-
Optional LLM prompt for AI-generated
metrics. When the prompt has been edited
via PATCH
/scorecards/scorecard-metrics/{id}, each
edit is stored as a new prompt version;
the value returned here is the most
recently created version (the active
prompt).
example: >-
Analyze the conversation duration and
provide insights
required:
- id
- name
- unit
- unitAbbreviated
- metricType
description: Configuration for a scorecard metric
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
default:
- color: RED
lowRange: 0
highRange: 49
- color: YELLOW
lowRange: 50
highRange: 79
- color: GREEN
lowRange: 80
highRange: 100
createdAt:
type: string
updatedAt:
type: string
organizationId:
type: string
conversationType:
type: string
isActive:
type: boolean
scorecardTemplateId:
type: string
scorecardConfigId:
type: string
minDurationMs:
type: number
default: 0
editable:
type: boolean
hasScoredRecordings:
type: boolean
default: false
required:
- id
- name
- nodes
- metricRubrics
- sectionWeights
- metricConfigurations
- createdAt
- updatedAt
- organizationId
- conversationType
- isActive
- scorecardConfigId
- editable
required:
- scorecardInstances
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:
````