Sessions#

class Sessions(client, spans, *, _guard=None)#

Bases: object

add_session_annotation(*, session_id, annotation_name, annotator_kind='HUMAN', label=None, score=None, explanation=None, metadata=None, identifier=None, sync=False)#

Add a single session annotation.

Requires Phoenix server >= 12.0.0.

Parameters:

  • session_id (str) – The ID of the session to annotate.

  • annotation_name (str) – The name of the annotation.

  • annotator_kind (Literal["LLM", "CODE", "HUMAN"]) – The kind of annotator used for the annotation. Must be one of “LLM”, “CODE”, or “HUMAN”. Defaults to “HUMAN”.

  • label (Optional[str]) – The label assigned by the annotation.

  • score (Optional[float]) – The score assigned by the annotation.

  • explanation (Optional[str]) – Explanation of the annotation result.

  • metadata (Optional[dict[str, Any]]) – Additional metadata for the annotation.

  • identifier (Optional[str]) – An optional identifier for the annotation. Each annotation is uniquely identified by the combination of name, session_id, and identifier (where a null identifier is equivalent to an empty string). If an annotation with the same name, session_id, and identifier already exists, it will be updated. Using a non-empty identifier allows you to have multiple annotations with the same name and session_id. Most of the time, you can leave this as None - it will still update the record if it exists. It will also update the record with identifier=”” if it exists.

  • sync (bool) – If True, the request will be fulfilled synchronously and the response will contain the inserted annotation ID. If False, the request will be processed asynchronously. Defaults to False.

Returns:

If sync is True, the inserted session annotation. If sync is False, None.

Return type:

Optional[InsertedSessionAnnotation]

Raises:

ValueError – If at least one of label, score, or explanation is not provided, or if required fields are invalid.

Example:

from phoenix.client import Client
client = Client()

# Add a session annotation
annotation = client.sessions.add_session_annotation(
    session_id="session_123",
    annotation_name="helpfulness",
    annotator_kind="HUMAN",
    label="helpful",
    score=0.9,
    explanation="This session was very helpful",
    sync=True
)
bulk_delete(*, session_ids, timeout=DEFAULT_TIMEOUT_IN_SECONDS)#

Delete multiple sessions by their identifiers.

All identifiers must be the same type: either all GlobalIDs or all user-provided session_id strings. Non-existent IDs are silently skipped. All associated traces, spans, and annotations are cascade deleted.

Requires Phoenix server >= 13.13.0.

Parameters:

  • session_ids – List of session identifiers (GlobalIDs or session_id strings).

  • timeout – Optional timeout in seconds for the request.

delete(*, session_id, timeout=DEFAULT_TIMEOUT_IN_SECONDS)#

Delete a session by ID or session_id string.

This will permanently remove the session and all associated traces, spans, and annotations via cascade delete.

Requires Phoenix server >= 13.13.0.

Parameters:

  • session_id – The session identifier (GlobalID or user-provided session_id).

  • timeout – Optional timeout in seconds for the request.

get(*, session_id, timeout=DEFAULT_TIMEOUT_IN_SECONDS)#

Get a session by ID or session_id string.

Requires Phoenix server >= 13.5.0.

Parameters:

  • session_id – The session identifier (GlobalID or user-provided session_id).

  • timeout – Optional timeout in seconds for the request.

Returns:

The session data.

get_session_turns(*, session_id, timeout=DEFAULT_TIMEOUT_IN_SECONDS)#

Experimental - Retrieve the ordered conversation turns for a session.

Requires Phoenix server >= 13.5.0.

Fetches every trace in the session, locates each trace’s root span, and extracts the input.value / output.value attributes to build a chronological list of turns.

Parameters:

  • session_id – The session to look up. Accepts either a Phoenix GlobalID (e.g. "U2Vzc2lvbjox") or the user-provided session_id string that was set at trace time.

  • timeout – Per-request timeout in seconds. Applied independently to the session fetch and to each batch of span fetches. Defaults to DEFAULT_TIMEOUT_IN_SECONDS.

Returns:

A list of SessionTurn dicts sorted by start_time (ascending). Each entry contains trace_id, start_time, end_time, and optionally input, output, and root_span.

Example:

client = Client()
turns = client.sessions.get_session_turns(session_id="my-session")
for turn in turns:
    print(turn.get("input", {}).get("value", "<no input>"))
get_sessions_dataframe(*, project_id=None, project_name=None, limit=None, timeout=DEFAULT_TIMEOUT_IN_SECONDS)#

Get sessions as a pandas DataFrame.

Requires Phoenix server >= 13.5.0.

Parameters:

  • project_id – The ID of the project.

  • project_name – The name of the project.

  • limit – Maximum number of sessions to return.

  • timeout – Optional timeout in seconds for the request.

Returns:

id, session_id, project_id, start_time, end_time, num_traces.

Return type:

A DataFrame with columns

list(*, project_id=None, project_name=None, limit=None, timeout=DEFAULT_TIMEOUT_IN_SECONDS)#

List sessions for a project.

Requires Phoenix server >= 13.5.0.

Parameters:

  • project_id – The ID of the project.

  • project_name – The name of the project.

  • limit – Maximum number of sessions to return.

  • timeout – Optional timeout in seconds for the request.

Returns:

A list of session data.

log_session_annotations(*, session_annotations, sync=False)#

Log multiple session annotations.

Requires Phoenix server >= 12.0.0.

Parameters:

  • session_annotations (Iterable[SessionAnnotationData]) – An iterable of session annotation data to log. Each annotation must include at least a session_id, name, and annotator_kind, and at least one of label, score, or explanation.

  • sync (bool) – If True, the request will be fulfilled synchronously and the response will contain the inserted annotation IDs. If False, the request will be processed asynchronously. Defaults to False.

Returns:

If sync is True, a list of all inserted session

annotations. If sync is False, None.

Return type:

Optional[list[InsertedSessionAnnotation]]

Raises:

  • httpx.HTTPError – If the request fails.

  • ValueError – If the response is invalid or if the input is invalid.

Example:

from phoenix.client import Client
client = Client()

# Log multiple session annotations
annotations = [
    {
        "session_id": "session_123",
        "name": "helpfulness",
        "annotator_kind": "HUMAN",
        "result": {"label": "helpful", "score": 0.9}
    },
    {
        "session_id": "session_456",
        "name": "relevance",
        "annotator_kind": "LLM",
        "result": {"label": "relevant", "score": 0.8}
    }
]
client.sessions.log_session_annotations(session_annotations=annotations)
log_session_annotations_dataframe(*, dataframe, annotation_name=None, annotator_kind=None, sync=False)#

Log multiple session annotations from a pandas DataFrame.

Requires Phoenix server >= 12.0.0.

This method allows you to create multiple session annotations at once by providing the data in a pandas DataFrame. The DataFrame can either include name or annotation_name columns (but not both) and annotator_kind column, or you can specify global values for all rows. The data is processed in chunks of 100 rows for efficient batch processing.

Parameters:

  • dataframe (pd.DataFrame) – A pandas DataFrame containing the annotation data. Must include either a “name” or “annotation_name” column (but not both) or provide a global annotation_name parameter. Similarly, must include an “annotator_kind” column or provide a global annotator_kind. The session_id can be either a column in the DataFrame or will be taken from the DataFrame index. Optional columns include: “label”, “score”, “explanation”, “metadata”, and “identifier”.

  • annotation_name (Optional[str]) – The name to use for all annotations. If provided, this value will be used for all rows and the DataFrame does not need to include a “name” or “annotation_name” column.

  • annotator_kind (Optional[Literal["LLM", "CODE", "HUMAN"]]) – The kind of annotator used for all annotations. If provided, this value will be used for all rows and the DataFrame does not need to include an “annotator_kind” column. Must be one of “LLM”, “CODE”, or “HUMAN”.

  • sync (bool) – If True, the request will be fulfilled synchronously and the response will contain the inserted annotation IDs. If False, the request will be processed asynchronously. Defaults to False.

Returns:

If sync is True, a list of all inserted session

annotations. If sync is False, None.

Return type:

Optional[list[InsertedSessionAnnotation]]

Raises:

  • ImportError – If pandas is not installed.

  • ValueError – If the DataFrame is missing required columns or if no valid annotation data is provided.

Example:

import pandas as pd
from phoenix.client import Client
client = Client()

# Using name and annotator_kind from DataFrame with session_id column
df1 = pd.DataFrame({
    "name": ["sentiment", "toxicity"],
    "session_id": ["session_123", "session_456"],
    "annotator_kind": ["HUMAN", "LLM"],
    "label": ["positive", "low"],
    "score": [0.9, 0.1]
})
client.sessions.log_session_annotations_dataframe(dataframe=df1)

# Using global name and annotator_kind with session_id from index
df2 = pd.DataFrame({
    "label": ["positive", "low"]
}, index=["session_345", "session_678"])
client.sessions.log_session_annotations_dataframe(
    dataframe=df2,
    annotation_name="sentiment",  # applies to all rows
    annotator_kind="HUMAN"  # applies to all rows
)
class AsyncSessions(client, spans, *, _guard=None)#

Bases: object

async add_session_annotation(*, session_id, annotation_name, annotator_kind='HUMAN', label=None, score=None, explanation=None, metadata=None, identifier=None, sync=False)#

Add a single session annotation.

Requires Phoenix server >= 12.0.0.

Parameters:

  • session_id (str) – The ID of the session to annotate.

  • annotation_name (str) – The name of the annotation.

  • annotator_kind (Literal["LLM", "CODE", "HUMAN"]) – The kind of annotator used for the annotation. Must be one of “LLM”, “CODE”, or “HUMAN”. Defaults to “HUMAN”.

  • label (Optional[str]) – The label assigned by the annotation.

  • score (Optional[float]) – The score assigned by the annotation.

  • explanation (Optional[str]) – Explanation of the annotation result.

  • metadata (Optional[dict[str, Any]]) – Additional metadata for the annotation.

  • identifier (Optional[str]) – An optional identifier for the annotation. Each annotation is uniquely identified by the combination of name, session_id, and identifier (where a null identifier is equivalent to an empty string). If an annotation with the same name, session_id, and identifier already exists, it will be updated. Using a non-empty identifier allows you to have multiple annotations with the same name and session_id. Most of the time, you can leave this as None - it will still update the record if it exists. It will also update the record with identifier=”” if it exists.

  • sync (bool) – If True, the request will be fulfilled synchronously and the response will contain the inserted annotation ID. If False, the request will be processed asynchronously. Defaults to False.

Returns:

If sync is True, the inserted session annotation. If sync is False, None.

Return type:

Optional[InsertedSessionAnnotation]

Raises:

ValueError – If at least one of label, score, or explanation is not provided, or if required fields are invalid.

Example:

from phoenix.client import Client
async_client = Client(async_client=True)

# Add a session annotation
annotation = await async_client.sessions.add_session_annotation(
    session_id="session_123",
    annotation_name="helpfulness",
    annotator_kind="HUMAN",
    label="helpful",
    score=0.9,
    explanation="This session was very helpful",
    sync=True
)
async bulk_delete(*, session_ids, timeout=DEFAULT_TIMEOUT_IN_SECONDS)#

Delete multiple sessions by their identifiers.

All identifiers must be the same type: either all GlobalIDs or all user-provided session_id strings. Non-existent IDs are silently skipped. All associated traces, spans, and annotations are cascade deleted.

Requires Phoenix server >= 13.13.0.

Parameters:

  • session_ids – List of session identifiers (GlobalIDs or session_id strings).

  • timeout – Optional timeout in seconds for the request.

async delete(*, session_id, timeout=DEFAULT_TIMEOUT_IN_SECONDS)#

Delete a session by ID or session_id string.

This will permanently remove the session and all associated traces, spans, and annotations via cascade delete.

Requires Phoenix server >= 13.13.0.

Parameters:

  • session_id – The session identifier (GlobalID or user-provided session_id).

  • timeout – Optional timeout in seconds for the request.

async get(*, session_id, timeout=DEFAULT_TIMEOUT_IN_SECONDS)#

Get a session by ID or session_id string.

Requires Phoenix server >= 13.5.0.

Parameters:

  • session_id – The session identifier (GlobalID or user-provided session_id).

  • timeout – Optional timeout in seconds for the request.

Returns:

The session data.

async get_session_turns(*, session_id, timeout=DEFAULT_TIMEOUT_IN_SECONDS)#

Experimental - Retrieve the ordered conversation turns for a session.

Requires Phoenix server >= 13.5.0.

Async version of Sessions.get_session_turns. Fetches every trace in the session, locates each trace’s root span, and extracts the input.value / output.value attributes to build a chronological list of turns.

Parameters:

  • session_id – The session to look up. Accepts either a Phoenix GlobalID (e.g. "U2Vzc2lvbjox") or the user-provided session_id string that was set at trace time.

  • timeout – Per-request timeout in seconds. Applied independently to the session fetch and to each batch of span fetches. Defaults to DEFAULT_TIMEOUT_IN_SECONDS.

Returns:

A list of SessionTurn dicts sorted by start_time (ascending). Each entry contains trace_id, start_time, end_time, and optionally input, output, and root_span.

Example:

async_client = AsyncClient()
turns = await async_client.sessions.get_session_turns(
    session_id="my-session",
)
for turn in turns:
    print(turn.get("input", {}).get("value", "<no input>"))
async get_sessions_dataframe(*, project_id=None, project_name=None, limit=None, timeout=DEFAULT_TIMEOUT_IN_SECONDS)#

Get sessions as a pandas DataFrame.

Requires Phoenix server >= 13.5.0.

Parameters:

  • project_id – The ID of the project.

  • project_name – The name of the project.

  • limit – Maximum number of sessions to return.

  • timeout – Optional timeout in seconds for the request.

Returns:

id, session_id, project_id, start_time, end_time, num_traces.

Return type:

A DataFrame with columns

async list(*, project_id=None, project_name=None, limit=None, timeout=DEFAULT_TIMEOUT_IN_SECONDS)#

List sessions for a project.

Requires Phoenix server >= 13.5.0.

Parameters:

  • project_id – The ID of the project.

  • project_name – The name of the project.

  • limit – Maximum number of sessions to return.

  • timeout – Optional timeout in seconds for the request.

Returns:

A list of session data.

async log_session_annotations(*, session_annotations, sync=False)#

Log multiple session annotations asynchronously.

Requires Phoenix server >= 12.0.0.

Parameters:

  • session_annotations (Iterable[SessionAnnotationData]) – An iterable of session annotation data to log. Each annotation must include at least a session_id, name, and annotator_kind, and at least one of label, score, or explanation.

  • sync (bool) – If True, the request will be fulfilled synchronously and the response will contain the inserted annotation IDs. If False, the request will be processed asynchronously. Defaults to False.

Returns:

If sync is True, a list of all inserted session

annotations. If sync is False, None.

Return type:

Optional[list[InsertedSessionAnnotation]]

Raises:

  • httpx.HTTPError – If the request fails.

  • ValueError – If the response is invalid or if the input is invalid.

Example:

from phoenix.client import AsyncClient
async_client = AsyncClient()

# Log multiple session annotations
annotations = [
    {
        "session_id": "session_123",
        "name": "helpfulness",
        "annotator_kind": "HUMAN",
        "result": {"label": "helpful", "score": 0.9}
    },
    {
        "session_id": "session_456",
        "name": "relevance",
        "annotator_kind": "LLM",
        "result": {"label": "relevant", "score": 0.8}
    }
]
await async_client.sessions.log_session_annotations(session_annotations=annotations)
async log_session_annotations_dataframe(*, dataframe, annotation_name=None, annotator_kind=None, sync=False)#

Log multiple session annotations from a pandas DataFrame asynchronously.

Requires Phoenix server >= 12.0.0.

This method allows you to create multiple session annotations at once by providing the data in a pandas DataFrame. The DataFrame can either include name or annotation_name columns (but not both) and annotator_kind column, or you can specify global values for all rows. The data is processed in chunks of 100 rows for efficient batch processing.

Parameters:

  • dataframe (pd.DataFrame) – A pandas DataFrame containing the annotation data. Must include either a “name” or “annotation_name” column (but not both) or provide a global annotation_name parameter. Similarly, must include an “annotator_kind” column or provide a global annotator_kind. The session_id can be either a column in the DataFrame or will be taken from the DataFrame index. Optional columns include: “label”, “score”, “explanation”, “metadata”, and “identifier”.

  • annotation_name (Optional[str]) – The name to use for all annotations. If provided, this value will be used for all rows and the DataFrame does not need to include a “name” or “annotation_name” column.

  • annotator_kind (Optional[Literal["LLM", "CODE", "HUMAN"]]) – The kind of annotator used for all annotations. If provided, this value will be used for all rows and the DataFrame does not need to include an “annotator_kind” column. Must be one of “LLM”, “CODE”, or “HUMAN”.

  • sync (bool) – If True, the request will be fulfilled synchronously and the response will contain the inserted annotation IDs. If False, the request will be processed asynchronously. Defaults to False.

Returns:

If sync is True, a list of all inserted session

annotations. If sync is False, None.

Return type:

Optional[list[InsertedSessionAnnotation]]

Raises:

  • ImportError – If pandas is not installed.

  • ValueError – If the DataFrame is missing required columns or if no valid annotation data is provided.

Example:

import pandas as pd
from phoenix.client import AsyncClient
async_client = AsyncClient()

# Using name and annotator_kind from DataFrame with session_id column
df1 = pd.DataFrame({
    "name": ["sentiment", "toxicity"],
    "session_id": ["session_123", "session_456"],
    "annotator_kind": ["HUMAN", "LLM"],
    "label": ["positive", "low"],
    "score": [0.9, 0.1]
})
await async_client.sessions.log_session_annotations_dataframe(dataframe=df1)

# Using global name and annotator_kind with session_id from index
df2 = pd.DataFrame({
    "label": ["positive", "low"]
}, index=["session_345", "session_678"])
await async_client.sessions.log_session_annotations_dataframe(
    dataframe=df2,
    annotation_name="sentiment",  # applies to all rows
    annotator_kind="HUMAN"  # applies to all rows
)