Skip to main content

​
Overview

Use this flow to test your agent by joining a Pipecat session via WebRTC for each evaluator run. Each item you submit will create a run that connects using your provided Pipecat session URL and configuration.
Each array element you send creates a separate run. To run the same scenario multiple times in parallel, repeat that scenario object multiple times in the payload.

​
How It Works

In the manual flow, you manage the Pipecat session lifecycle yourself:
  1. Create a Pipecat session using the Pipecat start session endpoint
  2. Receive the Daily.co room URL and token from Pipecat’s response
  3. Submit the room URL and token to Cekura along with your test scenario ID
  4. Cekura joins the WebRTC room and executes your test scenario
  5. Session cleanup is handled by your application or Pipecat
This approach gives you full control over session creation, room configuration, and lifecycle management.

​
Prerequisites

  • A Cekura account
  • One or more scenarios created for your agent
  • Pipecat agent endpoint and any required authentication tokens for each run you intend to start

​
API Endpoint

  • Method: POST
  • URL: https://api.cekura.ai/test_framework/v1/scenarios-external/run_scenarios_pipecat/
  • Headers:
    • X-CEKURA-API-KEY: your API key
    • Content-Type: application/json

​
Request Body

  • scenarios: Array of objects. Each object fields:
    • scenario (number, required): Scenario ID
    • pipecat_room_url (string, required): Pipecat WebRTC room URL to connect to
    • pipecat_token (string, optional): Authentication token for the Pipecat room
    • publish_data_message (object, optional): JSON data message to publish during the session

​
Example: Minimal Single Run (cURL)

curl -X POST \
  'https://api.cekura.ai/test_framework/v1/scenarios-external/run_scenarios_pipecat/' \
  -H 'X-CEKURA-API-KEY: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "scenarios": [
      {
        "scenario": 30,
        "pipecat_room_url": "https://<PIPECAT_ROOM_URL>",
        "pipecat_token": "<PIPECAT_TOKEN>"
      }
    ]
  }'

​
Example: Multiple Runs (JSON)

{
  "scenarios": [
    {
      "scenario": 30,
      "pipecat_room_url": "https://<PIPECAT_ROOM_URL>",
      "pipecat_token": "<PIPECAT_TOKEN_1>"
    },
    {
      "scenario": 31,
      "pipecat_room_url": "https://<PIPECAT_ROOM_URL>",
      "pipecat_token": "<PIPECAT_TOKEN_2>",
      "publish_data_message": {
        "custom_field": "custom_value"
      }
    }
  ]
}

​
Example: Python

import requests

API_KEY = "<YOUR_API_KEY>"
BASE_URL = "https://api.cekura.ai/test_framework"

headers = {
    "X-CEKURA-API-KEY": API_KEY,
    "Content-Type": "application/json",
}

payload = {
    "scenarios": [
        {
            "scenario": 30,  # Cekura scenario ID
            "pipecat_room_url": "https://<PIPECAT_ROOM_URL>",  # Daily.co room URL
            "pipecat_token": "<PIPECAT_TOKEN_1>"  # Daily meeting token
        },
        {
            "scenario": 31,  # Cekura scenario ID
            "pipecat_room_url": "https://<PIPECAT_ROOM_URL>",  # Daily.co room URL
            "pipecat_token": "<PIPECAT_TOKEN_2>",  # Daily meeting token
            "publish_data_message": {  # Optional custom data
                "custom_field": "custom_value"
            },
        },
    ]
}

resp = requests.post(
    f"{BASE_URL}/v1/scenarios-external/run_scenarios_pipecat/",
    headers=headers,
    json=payload,
)
result = resp.json()
print(result)

​
Expected Behavior

  • A result is created and a run is queued for each item in scenarios
  • Each run connects to the provided Pipecat WebRTC room using the given token
  • You can poll run statuses using the Bulk Runs API:

API Reference

Get Runs with IDs: API Doc

​
Troubleshooting

  • 401/403 errors: Check your X-CEKURA-API-KEY
  • Connection failures: Verify pipecat_room_url and pipecat_token are correct
  • No runs created: Ensure the scenarios array is not empty and scenario IDs are valid
  • WebRTC connection issues: Ensure the Pipecat room URL is accessible and the token is valid for the session

​
Key Terminology

  • Pipecat Cloud: The hosted platform for deploying and managing Pipecat agents. Get your API key at pipecat.daily.co
  • Daily.co: WebRTC infrastructure provider that powers Pipecat’s voice and video capabilities. See Daily docs
  • Room URL: The Daily.co WebRTC endpoint where the test session occurs
  • Meeting Token: Authentication credential for joining a Daily.co room

​
Next Steps