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.

​
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,
            "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"
            },
        },
    ]
}

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

​
Next Steps