Skip to main content
GET
/
v1
/
core
/
scorecards
/
evaluated-instances
/
{id}
Get evaluated scorecard instance
curl --request GET \
  --url https://api.siro.ai/v1/core/scorecards/evaluated-instances/{id} \
  --header 'x-siro-auth-token: <api-key>'
{
  "data": {
    "id": "scorecard_001",
    "name": "Sales Performance Scorecard",
    "recordingsEvaluatedCount": 150,
    "recordingsWonCount": 45,
    "pointsPossible": 100,
    "pointsEarned": 75,
    "evaluatedNodes": [
      {
        "id": "node_001",
        "name": "Conversation Quality",
        "indexNumber": 1,
        "parentId": "root",
        "nodeType": "SECTION",
        "metadata": {
          "metricId": "metric_001",
          "metricType": "CONVERSATION_TIME"
        },
        "pointsPossible": 100,
        "pointsEarned": 75,
        "color": "GREEN",
        "description": "Metrics related to conversation quality and engagement",
        "metricValue": 85,
        "unit": "seconds",
        "unitAbbreviated": "sec"
      }
    ],
    "metricRubrics": [
      {
        "scorecardNodeId": "node_001",
        "scorecardMetricId": "metric_001",
        "metricPointTotal": 100,
        "minTarget": 0,
        "maxTarget": 100,
        "targetTolerance": 5
      }
    ],
    "sectionWeights": [
      {
        "scorecardNodeId": "node_001",
        "weight": 25
      }
    ],
    "colorConfigurations": [
      {
        "color": "GREEN",
        "lowRange": 80,
        "highRange": 100
      }
    ],
    "filterByIds": [
      "user_001",
      "user_002"
    ],
    "filterBy": "USER",
    "startAt": "2024-01-01T00:00:00Z",
    "endAt": "2024-01-31T23:59:59Z",
    "description": "Comprehensive evaluation of sales call performance",
    "tags": [
      "sales",
      "performance",
      "q1"
    ],
    "spotlightSummaries": [
      {
        "summary": "<string>",
        "title": "<string>",
        "score": 123,
        "recordings": [
          {
            "id": "<string>",
            "dateCreated": "<string>",
            "score": 123,
            "startTimeInMillis": 123,
            "endTimeInMillis": 123,
            "quote": "<string>",
            "title": "<string>"
          }
        ]
      }
    ]
  },
  "cursor": "<string>",
  "pageSize": 123,
  "limit": 123,
  "total": 123,
  "hasNextPage": true
}

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.

​
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 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 with filterBy=RECORDING. See the overview for guidance on when to pick which.

​
Picking filterBy and filterByIds

filterByWhat filterByIds should beTypical use
RECORDINGOne or more recording idsScore a specific call against the saved scorecard
USERA Siro user idRep-level rollup across the date range; also returns spotlightSummaries
TEAMA team idTeam-level rollup
ORGANIZATIONThe 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.

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.

Path Parameters

​
id
string
required

Query Parameters

​
startAt
string
required

Start date for the evaluation range (ISO 8601 format)

Example:

"2024-01-01T00:00:00Z"

​
endAt
string
required

End date for the evaluation range (ISO 8601 format)

Example:

"2024-01-31T23:59:59Z"

​
filterByIds
required

IDs to filter by (can be array or single string)

Minimum array length: 1
Example:
["recording_001", "recording_002"]
​
filterBy
required

Entity type to filter by (RECORDING, USER, TEAM, ORGANIZATION)

Minimum array length: 1

The entity type to filter scorecard metrics by

Available options:
RECORDING,
USER,
TEAM,
ORGANIZATION
Example:

"RECORDING"

​
groupBy

Optional grouping for the evaluation results

Minimum array length: 1

The entity type to filter scorecard metrics by

Available options:
RECORDING,
USER,
TEAM,
ORGANIZATION
Example:

"USER"

Response

Get evaluated scorecard instance

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