Get Simulation Runs

Retrieve run-level records with eval scores, scenario metadata, and per-call breakdowns.

Get Simulation Runs

Returns run records with evaluation scores, scenario metadata, and call details. Use this to inspect what happened in each execution and why calls passed or failed.

GET https://api.futureagi.com/sdk/api/v1/simulation/runs/

Authentication

This endpoint uses API key authentication. Include both headers in every request:

X-Api-Key: YOUR_API_KEY
X-Secret-Key: YOUR_SECRET_KEY

Query Parameters

ParameterTypeRequiredDescription
run_test_namestringOne of these is requiredName of the run test. Returns paginated list of executions with eval scores.
execution_idUUIDUUID of a test execution. Returns one execution with paginated call results.
call_execution_idUUIDUUID of a call execution. Returns full detail for that call.
eval_namestringNoComma-separated eval names to filter. Only matching evals are returned. Example: Coherence,Tone
summarybooleanNoInclude the FMA (Fix My Agent) explanation summary. Default: false.
pageintegerNoPage number for paginated results. Default: 1.
limitintegerNoNumber of results per page. Default: 10.

Responses

200 — By call_execution_id

Returns full detail for a single call including eval outputs, latency, and cost.

{
  "status": true,
  "result": {
    "call_execution_id": "5af9e484-...",
    "execution_id": "2b19f6e6-...",
    "scenario_id": "cc3c8111-...",
    "scenario_name": "Billing Inquiry",
    "status": "completed",
    "started_at": "2026-03-23T20:01:04.450Z",
    "completed_at": "2026-03-23T20:02:32.123Z",
    "duration_seconds": 88,
    "ended_reason": "customer-ended-call",
    "call_summary": "Customer called about a billing discrepancy...",
    "eval_outputs": {
      "eval-config-1": {
        "name": "Coherence",
        "output": "Passed",
        "output_type": "Pass/Fail",
        "reason": "Agent maintained context throughout the conversation."
      },
      "eval-config-2": {
        "name": "Resolution",
        "output": false,
        "output_type": "Pass/Fail",
        "reason": "Customer hung up without resolution."
      }
    },
    "latency": {
      "avg_agent_latency_ms": 1234,
      "response_time_ms": null
    },
    "cost": {
      "total_cost_cents": 24,
      "stt_cost_cents": 0,
      "llm_cost_cents": 0,
      "tts_cost_cents": 0
    }
  }
}

200 — By execution_id

Returns one execution with eval summary and paginated per-call breakdown.

{
  "status": true,
  "result": {
    "execution_id": "aabfa5b5-...",
    "status": "completed",
    "started_at": "2026-01-19T07:42:26.006Z",
    "completed_at": "2026-01-19T08:15:00.000Z",
    "total_calls": 30,
    "completed_calls": 26,
    "failed_calls": 4,
    "eval_results": [
      {
        "name": "is_helpful",
        "id": "e283f838-...",
        "output_type": "Pass/Fail",
        "total_pass_rate": 80.77,
        "result": [
          {
            "name": "helpful_or_no",
            "id": "bcff05d0-...",
            "total_cells": 26,
            "output": {
              "pass": 80.77,
              "fail": 19.23,
              "pass_count": 21,
              "fail_count": 5
            }
          }
        ]
      }
    ],
    "call_results": {
      "total_pages": 3,
      "current_page": 1,
      "count": 30,
      "results": [
        {
          "call_execution_id": "839b6662-...",
          "scenario_id": "d6607d90-...",
          "scenario_name": "Billing Inquiry",
          "status": "completed",
          "duration_seconds": 120,
          "eval_outputs": {
            "eval-config-1": {
              "name": "is_helpful",
              "output": "Passed",
              "output_type": "Pass/Fail"
            }
          }
        }
      ]
    }
  }
}

200 — By execution_id with summary=true

Same as above, with additional FMA explanation fields.

{
  "status": true,
  "result": {
    "execution_id": "...",
    "eval_results": [...],
    "call_results": {...},
    "eval_explanation_summary": {
      "is_helpful": [
        {
          "cluster_name": "Pricing contradictions",
          "call_execution_ids": ["uuid1", "uuid2"],
          "description": "Agent gives different prices for the same product."
        }
      ]
    },
    "eval_explanation_summary_status": "completed"
  }
}

200 — By run_test_name

Returns a paginated list of all executions for the run test, each with eval scores.

{
  "status": true,
  "result": {
    "total_pages": 12,
    "current_page": 1,
    "count": 12,
    "results": [
      {
        "execution_id": "75f6a314-...",
        "status": "completed",
        "started_at": "2026-03-05T10:12:32.790Z",
        "completed_at": "2026-03-05T10:45:00.000Z",
        "total_calls": 30,
        "completed_calls": 28,
        "failed_calls": 2,
        "eval_results": [...]
      }
    ]
  }
}

400

Missing or invalid parameters.

404

The specified run test, execution, or call execution was not found.

500

Internal server error.

Code Examples

cURL

# Get all executions for a run test
curl "https://api.futureagi.com/sdk/api/v1/simulation/runs/?run_test_name=My%20Agent%20Test" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY"

# Get one execution with FMA summary
curl "https://api.futureagi.com/sdk/api/v1/simulation/runs/?execution_id=YOUR_EXECUTION_ID&summary=true" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY"

# Get one call, filtered to specific evals
curl "https://api.futureagi.com/sdk/api/v1/simulation/runs/?call_execution_id=YOUR_CALL_ID&eval_name=Coherence,Tone" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY"

Python

import requests

url = "https://api.futureagi.com/sdk/api/v1/simulation/runs/"
headers = {
    "X-Api-Key": "YOUR_API_KEY",
    "X-Secret-Key": "YOUR_SECRET_KEY",
}

# Get execution with call breakdown and failure reasons
response = requests.get(url, headers=headers, params={
    "execution_id": "YOUR_EXECUTION_ID",
    "summary": "true",
})
data = response.json()

# Extract failure reasons for your LLM pipeline
for call in data["result"]["call_results"]["results"]:
    for eval_id, eval_data in call["eval_outputs"].items():
        if eval_data.get("output") in [False, "Failed"]:
            print(f"Failed: {eval_data['name']} — {eval_data.get('reason')}")

JavaScript

const response = await fetch(
  "https://api.futureagi.com/sdk/api/v1/simulation/runs/?execution_id=YOUR_EXECUTION_ID&summary=true",
  {
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "X-Secret-Key": "YOUR_SECRET_KEY",
    },
  }
);

const data = await response.json();
const { eval_results, eval_explanation_summary } = data.result;

// Check if agent is ready to promote
const allPassing = eval_results.every(e => e.total_pass_rate > 90);
console.log(`Agent ${allPassing ? "ready" : "needs work"}`);
GET /
Authentication
REQUEST 
 
 
  
 
 RESPONSE