> For the complete documentation index, see [llms.txt](https://docs.interactive.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interactive.ai/sdk/scoring.md).

# Scoring

## Overview

Attach numeric, boolean, or categorical scores to traces and spans.

`create_score` posts a score to any trace or observation by ID. `score_current_span` and `score_current_trace` resolve the active OTel context automatically.

***

## `create_score` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L1934)

Create a score for a specific trace or observation.

This method creates a score for evaluating a InteractiveAI trace or observation. Scores can be used to track quality metrics, user feedback, or automated evaluations.

```python
create_score(
    *,
    name: str,
    value: Union[float, str],
    session_id: str | None = None,
    dataset_run_id: str | None = None,
    trace_id: str | None = None,
    observation_id: str | None = None,
    score_id: str | None = None,
    data_type: Literal['NUMERIC', 'CATEGORICAL', 'BOOLEAN'] | None = None,
    comment: str | None = None,
    config_id: str | None = None,
    metadata: Any | None = None,
    timestamp: datetime | None = None,
) -> None
```

**Parameters**

* `name` — Name of the score (e.g., "relevance", "accuracy")
* `value` — Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL)
* `session_id` — ID of the InteractiveAI session to associate the score with
* `dataset_run_id` — ID of the InteractiveAI dataset run to associate the score with
* `trace_id` — ID of the InteractiveAI trace to associate the score with
* `observation_id` — Optional ID of the specific observation to score. Trace ID must be provided too.
* `score_id` — Optional custom ID for the score (auto-generated if not provided)
* `data_type` — Type of score (NUMERIC, BOOLEAN, or CATEGORICAL)
* `comment` — Optional comment or explanation for the score
* `config_id` — Optional ID of a score config defined in InteractiveAI
* `metadata` — Optional metadata to be attached to the score
* `timestamp` — Optional timestamp for the score (defaults to current UTC time)

**Example**

```python
# Create a numeric score for accuracy
interactiveai.create_score(
    name="accuracy",
    value=0.92,
    trace_id="abcdef1234567890abcdef1234567890",
    data_type="NUMERIC",
    comment="High accuracy with minor irrelevant details"
)

# Create a categorical score for sentiment
interactiveai.create_score(
    name="sentiment",
    value="positive",
    trace_id="abcdef1234567890abcdef1234567890",
    observation_id="abcdef1234567890",
    data_type="CATEGORICAL"
)
```

***

## `score_current_span` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L2029)

Create a score for the current active span.

This method scores the currently active span in the context. It's a convenient way to score the current operation without needing to know its trace and span IDs.

```python
score_current_span(
    *,
    name: str,
    value: Union[float, str],
    score_id: str | None = None,
    data_type: Literal['NUMERIC', 'CATEGORICAL', 'BOOLEAN'] | None = None,
    comment: str | None = None,
    config_id: str | None = None,
) -> None
```

**Parameters**

* `name` — Name of the score (e.g., "relevance", "accuracy")
* `value` — Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL)
* `score_id` — Optional custom ID for the score (auto-generated if not provided)
* `data_type` — Type of score (NUMERIC, BOOLEAN, or CATEGORICAL)
* `comment` — Optional comment or explanation for the score
* `config_id` — Optional ID of a score config defined in InteractiveAI

**Example**

```python
with interactiveai.start_as_current_generation(name="answer-query") as generation:
    # Generate answer
    response = generate_answer(...)
    generation.update(output=response)

    # Score the generation
    interactiveai.score_current_span(
        name="relevance",
        value=0.85,
        data_type="NUMERIC",
        comment="Mostly relevant but contains some tangential information"
    )
```

***

## `score_current_trace` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L2101)

Create a score for the current trace.

This method scores the trace of the currently active span. Unlike score\_current\_span, this method associates the score with the entire trace rather than a specific span. It's useful for scoring overall performance or quality of the entire operation.

```python
score_current_trace(
    *,
    name: str,
    value: Union[float, str],
    score_id: str | None = None,
    data_type: Literal['NUMERIC', 'CATEGORICAL', 'BOOLEAN'] | None = None,
    comment: str | None = None,
    config_id: str | None = None,
) -> None
```

**Parameters**

* `name` — Name of the score (e.g., "user\_satisfaction", "overall\_quality")
* `value` — Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL)
* `score_id` — Optional custom ID for the score (auto-generated if not provided)
* `data_type` — Type of score (NUMERIC, BOOLEAN, or CATEGORICAL)
* `comment` — Optional comment or explanation for the score
* `config_id` — Optional ID of a score config defined in InteractiveAI

**Example**

```python
with interactiveai.start_as_current_span(name="process-user-request") as span:
    # Process request
    result = process_complete_request()
    span.update(output=result)

    # Score the overall trace
    interactiveai.score_current_trace(
        name="overall_quality",
        value=0.95,
        data_type="NUMERIC",
        comment="High quality end-to-end response"
    )
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.interactive.ai/sdk/scoring.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.