Skip to main content
GET
/
v1
/
core
/
scorecards
/
instances
Get scorecard instances
curl --request GET \
  --url https://api.siro.ai/v1/core/scorecards/instances \
  --header 'x-siro-auth-token: <api-key>'
{
  "data": {
    "scorecardInstances": [
      {
        "id": "<string>",
        "name": "<string>",
        "nodes": [
          {
            "id": "node_001",
            "name": "Conversation Quality",
            "indexNumber": 1,
            "parentId": "root",
            "nodeType": "SECTION",
            "metadata": {
              "metricId": "metric_001",
              "metricType": "CONVERSATION_TIME"
            },
            "description": "Metrics related to conversation quality and engagement"
          }
        ],
        "metricRubrics": [
          {
            "scorecardNodeId": "node_001",
            "scorecardMetricId": "metric_001",
            "metricPointTotal": 100,
            "minTarget": 0,
            "maxTarget": 100,
            "targetTolerance": 5
          }
        ],
        "sectionWeights": [
          {
            "scorecardNodeId": "node_001",
            "weight": 25
          }
        ],
        "metricConfigurations": [
          {
            "id": "metric_001",
            "name": "Conversation Time",
            "unit": "seconds",
            "unitAbbreviated": "sec",
            "metricType": "CONVERSATION_TIME",
            "description": "Total duration of the conversation in seconds",
            "llmPrompt": "Analyze the conversation duration and provide insights"
          }
        ],
        "createdAt": "<string>",
        "updatedAt": "<string>",
        "organizationId": "<string>",
        "conversationType": "<string>",
        "isActive": true,
        "scorecardConfigId": "<string>",
        "editable": true,
        "description": "<string>",
        "colorConfigurations": [
          {
            "color": "RED",
            "lowRange": 0,
            "highRange": 49
          },
          {
            "color": "YELLOW",
            "lowRange": 50,
            "highRange": 79
          },
          {
            "color": "GREEN",
            "lowRange": 80,
            "highRange": 100
          }
        ],
        "scorecardTemplateId": "<string>",
        "minDurationMs": 0
      }
    ]
  },
  "cursor": "<string>",
  "pageSize": 123,
  "limit": 123,
  "total": 123,
  "hasNextPage": true
}

​
Why you’d call this

This is how you discover the scorecard instance id you’ll pass to 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:
1

List instances for the org and conversation type

Call this endpoint with organizationId (required) and optionally conversationTypeId and isActive=true.
2

Pick the instance id you want to evaluate

Most orgs have one active instance per conversation type. Each item in the response carries an id.
3

Run the evaluation

Pass that id to 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.

Authorizations

​
x-siro-auth-token
string
header
default:<oauth-access-token>
required

OAuth access token for user-scoped requests (Authorization Code or machine-to-machine). Send header x-siro-auth-token: <oauth-access-token>. Not an organization API key.

Query Parameters

​
organizationId
string
​
conversationTypeId
string
​
isActive
boolean | null

Response

Get scorecard instances

​
data
object
required
​
cursor
​
pageSize
number
​
limit
number
​
total
number | null
​
hasNextPage
boolean