Python SDK

The Python SDK is continually evolving, with new endpoints being added regularly. Stay tuned for updates!

Overview

The Roark Python SDK provides a streamlined way to interact with the Roark API. This guide covers the two most common workflows: uploading calls and running metrics, and executing simulation run plans.

Prerequisites

Before you begin, ensure you have:

Python 3.7 or higher - Download Python
A Roark API Key - Generate one here

Installation

Choose your preferred package manager:

pip install roark-analytics

pipenv install roark-analytics

poetry add roark-analytics

Initialize the Client

import os
from roark_analytics import Roark

client = Roark(
    bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"),
)

Set ROARK_API_BEARER_TOKEN in your environment, or replace with your actual API key from Roark.

Upload a Call and Run Metrics

Upload a call recording, then run metric definitions against it using a collection job.

Upload a Call

call = client.call.create(
    recording_url="https://example.com/recording.mp3",
    started_at="2024-01-15T10:00:00Z",
    interface_type="PHONE",
    call_direction="INBOUND",
    agent={
        "name": "Support Agent",
        "customId": "agent-123",
    },
    customer={
        "phoneNumberE164": "+15551234567",
    },
    # Optional: custom properties for filtering
    properties={
        "department": "sales",
        "campaignId": "summer-2024",
    },
)

Get Metric Definitions

List available metric definitions to choose which ones to run:

Metric definitions are cursor-paginated. list_definitions() returns the first page, up to 500 definitions. To enumerate further pages, pass the preceding response’s pagination.nextCursor as after to GET /v1/metric/definitions; treat the cursor as opaque.

definitions = client.metric.list_definitions()

# Find the metrics you want to collect
task_completion = next(
    m for m in definitions.data if m.metric_id == "task_completion"
)
sentiment = next(
    m for m in definitions.data if m.metric_id == "sentiment_score"
)

Create a Metric Collection Job

Run the selected metrics against your uploaded call:

job = client.metric_collection_job.create(
    call_ids=[call.data.id],
    metrics=[
        {"id": task_completion.id},
        {"id": sentiment.id},
    ],
)

Poll for Completion

import time

status = "PENDING"
while status not in ("COMPLETED", "FAILED"):
    result = client.metric_collection_job.get_by_id(job.data.id)
    status = result.data.status
    print(f"Progress: {result.data.completed_items}/{result.data.total_items}")
    if status not in ("COMPLETED", "FAILED"):
        time.sleep(2)

Fetch Results

metrics = client.call.list_metrics(call.data.id)
print(metrics.data)

If you have metric collectors configured, metrics are collected automatically when calls are uploaded, no collection job needed.

Run a Simulation

Run a simulation against your agent with an inline plan, then monitor it.

Run a Simulation

Reference an agent endpoint, a customer flow, and at least one metric. Add save_as_plan=True (with a name) to keep it as a reusable plan.

run = client.simulation.run(
    plan={
        "direction": "INBOUND",
        "maxSimulationDurationSeconds": 300,
        "agentEndpoints": [{"id": "agent-endpoint-uuid"}],
        "flows": [{"id": "customer-flow-uuid", "happyPath": True}],
        "metrics": [{"slug": "task_completion"}],
    },
)

job_id = run.data.simulation_run_plan_job_id

Or re-run a saved plan

job = client.simulation_run_plan_job.start("plan-uuid")

Monitor Progress

result = client.simulation_run_plan_job.get_by_id(job_id)

print(f"Status: {result.data.status}")
print(f"Jobs: {len(result.data.simulation_jobs)}")

View Results

Results including metric evaluations are available in the Roark dashboard, or you can fetch metrics for individual simulation calls via the API:

# Get metrics for a specific simulation call
metrics = client.call.list_metrics("simulation-call-id")

Additional Examples

Create a call with tool invocations

Track function calls and tool usage during the conversation:

call = client.call.create(
    recording_url="https://example.com/recording.mp3",
    started_at="2024-01-15T10:00:00Z",
    interface_type="PHONE",
    call_direction="INBOUND",
    agent={
        "name": "Booking Agent",
        "customId": "booking-agent-1",
    },
    customer={
        "phoneNumberE164": "+15551234567",
    },
    tool_invocations=[
        {
            "name": "check_availability",
            "description": "Check available appointment slots",
            "startOffsetMs": 5000,
            "endOffsetMs": 5500,
            "parameters": {
                "date": "2024-01-20",
                "serviceType": "consultation",
            },
            "result": {"slots": ["9:00 AM", "2:00 PM", "4:00 PM"]},
            "agent": {"customId": "booking-agent-1"},
        },
        {
            "name": "book_appointment",
            "description": "Book an appointment for the customer",
            "startOffsetMs": 15000,
            "endOffsetMs": 15800,
            "parameters": {
                "date": "2024-01-20",
                "time": "2:00 PM",
                "customerName": "John Doe",
            },
            "result": "Appointment confirmed",
            "agent": {"customId": "booking-agent-1"},
        },
    ],
)

Create a call with an existing agent

Reference an agent by its Roark ID or custom ID:

# By Roark ID
call = client.call.create(
    recording_url="https://example.com/recording.mp3",
    started_at="2024-01-15T10:00:00Z",
    interface_type="WEB",
    call_direction="OUTBOUND",
    agent={
        "roarkId": "550e8400-e29b-41d4-a716-446655440000",
    },
    customer={
        "phoneNumberE164": "+15551234567",
    },
)

# By custom ID
call2 = client.call.create(
    recording_url="https://example.com/recording.mp3",
    started_at="2024-01-15T10:00:00Z",
    interface_type="PHONE",
    call_direction="INBOUND",
    agent={
        "customId": "my-agent-id",
    },
    customer={
        "phoneNumberE164": "+15551234567",
    },
)

Create a metric collection job for multiple calls

Run metrics across a batch of existing calls:

job = client.metric_collection_job.create(
    call_ids=[
        "call-uuid-1",
        "call-uuid-2",
        "call-uuid-3",
    ],
    metrics=[
        {"id": "metric-definition-uuid-1"},
        {"id": "metric-definition-uuid-2"},
    ],
)

# total_items = len(call_ids) * len(metrics)
print(f"Processing {job.data.total_items} items")

Async usage

For asynchronous operations, use the async client:

import os
import asyncio
from roark_analytics import AsyncRoark

client = AsyncRoark(
    bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"),
)

async def main():
    call = await client.call.create(
        recording_url="https://example.com/recording.mp3",
        started_at="2024-01-15T10:00:00Z",
        interface_type="PHONE",
        call_direction="INBOUND",
        agent={"name": "Support Agent"},
        customer={"phoneNumberE164": "+15551234567"},
    )

    job = await client.metric_collection_job.create(
        call_ids=[call.data.id],
        metrics=[{"id": "metric-definition-uuid"}],
    )

asyncio.run(main())

Additional Resources

API Reference

Explore our comprehensive API documentation

Example Repository

View example implementations and use cases

PyPI Package

View package details and stats on PyPI

GitHub Repository

Browse the source code and contribute

Getting Started

Simulations

Observability

Metrics

Config as Code

Recipes

Integrations

Enterprise

SDKs & Developer Tools

Resources

Overview

Prerequisites

Installation

Initialize the Client

Upload a Call and Run Metrics

Run a Simulation

Additional Examples

Additional Resources

API Reference

Example Repository

PyPI Package

GitHub Repository

​Overview

​Prerequisites

​Installation

​Initialize the Client

​Upload a Call and Run Metrics

​Run a Simulation

​Additional Examples

​Additional Resources

API Reference

Example Repository

PyPI Package

GitHub Repository

Overview

Prerequisites

Installation

Initialize the Client

Upload a Call and Run Metrics

Run a Simulation

Additional Examples

Additional Resources