Get a simulation

curl --request GET \
  --url https://app.egma.ai/v1/simulations/{simulationId} \
  --header 'Authorization: Bearer <token>'

{
  "id": "<string>",
  "projectId": "<string>",
  "runId": "<string>",
  "runName": "<string>",
  "position": 123,
  "status": "queued",
  "workBlock": {
    "error": "allowance_spent",
    "message": "<string>"
  },
  "gradingState": "not_requested",
  "evidenceError": {
    "error": "evidence_collection_error",
    "message": "<string>"
  },
  "grades": [
    {
      "projectGraderId": "<string>",
      "graderDefinitionId": "<string>",
      "graderDefinitionVersion": 2,
      "parameterValues": {},
      "graderName": "<string>",
      "score": 0.5,
      "details": {
        "rationale": "<string>",
        "assertions": [
          {
            "key": "<string>",
            "decision": "met",
            "score": 0.5,
            "rationale": "<string>",
            "citedSpanIds": [
              "<string>"
            ],
            "citedTurns": [
              2
            ],
            "error": "<string>"
          }
        ],
        "error": "<string>"
      },
      "passThreshold": 0.5,
      "result": "passed",
      "gradedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "gradeHistory": [
    {
      "projectGraderId": "<string>",
      "graderDefinitionId": "<string>",
      "graderDefinitionVersion": 2,
      "parameterValues": {},
      "graderName": "<string>",
      "score": 0.5,
      "details": {
        "rationale": "<string>",
        "assertions": [
          {
            "key": "<string>",
            "decision": "met",
            "score": 0.5,
            "rationale": "<string>",
            "citedSpanIds": [
              "<string>"
            ],
            "citedTurns": [
              2
            ],
            "error": "<string>"
          }
        ],
        "error": "<string>"
      },
      "passThreshold": 0.5,
      "result": "passed",
      "gradedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "combinedScore": 0.5,
  "reason": "<string>",
  "executionFailure": "<string>",
  "modality": "voice",
  "createdAt": "2023-11-07T05:31:56Z",
  "startedAt": "2023-11-07T05:31:56Z",
  "endedAt": "2023-11-07T05:31:56Z",
  "providerReference": "<string>",
  "hasRecording": true,
  "agentPovComplete": true,
  "agentPovIncomplete": true,
  "measures": {
    "durationMs": 123,
    "turnCount": 123,
    "toolCallCount": 123,
    "erroredStepCount": 123,
    "humanTurnCount": 123,
    "agentTurnCount": 123
  },
  "metrics": [
    {
      "measure": "<string>",
      "unit": "<string>",
      "derived": true,
      "pov": "persona",
      "samples": [
        123
      ],
      "spanIds": [
        "<string>"
      ],
      "mean": 123,
      "p50": 123,
      "p90": 123,
      "partial": true,
      "reportedBy": "<string>",
      "otherPov": {
        "pov": "persona",
        "derived": true,
        "samples": [
          123
        ],
        "spanIds": [
          "<string>"
        ],
        "partial": true,
        "reportedBy": "<string>"
      }
    }
  ],
  "test": {
    "id": "<string>",
    "versionId": "<string>",
    "name": "<string>",
    "scenario": "<string>",
    "expectedBehaviors": [
      "<string>"
    ]
  },
  "persona": {
    "id": "<string>",
    "name": "<string>",
    "versionId": "<string>",
    "identityName": "<string>",
    "personality": "<string>",
    "language": "<string>"
  },
  "agent": {
    "id": "<string>",
    "name": "<string>",
    "archived": true
  },
  "connection": {
    "id": "<string>",
    "name": "<string>",
    "archived": true
  },
  "connectionSnapshot": {
    "agentPlatform": "<string>",
    "connectionType": "<string>",
    "accessVariant": "<string>",
    "modality": "voice",
    "topology": "<string>",
    "environment": "<string>",
    "config": "<unknown>"
  },
  "gradingPlan": {
    "capturedAt": "2023-11-07T05:31:56Z",
    "items": [
      {
        "projectGraderId": "<string>",
        "graderDefinitionId": "<string>",
        "graderDefinitionVersion": 2,
        "graderName": "<string>",
        "passThreshold": 0.5
      }
    ]
  },
  "transcript": {
    "traceId": "<string>",
    "startedAt": "2023-11-07T05:31:56Z",
    "endedAt": "2023-11-07T05:31:56Z",
    "durationNs": "<string>",
    "spanCount": 123,
    "turnCounts": {
      "human": 123,
      "agent": 123
    },
    "toolSpanCount": 123,
    "erroredSpanCount": 123,
    "turns": [
      {
        "spanId": "<string>",
        "parentSpanId": "<string>",
        "name": "<string>",
        "kind": "<string>",
        "status": "<string>",
        "startedAt": "2023-11-07T05:31:56Z",
        "durationNs": "<string>",
        "text": "<string>",
        "audioUrl": "<string>",
        "toolName": "<string>",
        "toolArguments": "<string>",
        "toolResult": "<string>",
        "pov": "persona",
        "spans": "<array>",
        "toolProvenance": "mocked"
      }
    ],
    "spans": [
      {
        "spanId": "<string>",
        "parentSpanId": "<string>",
        "name": "<string>",
        "kind": "<string>",
        "status": "<string>",
        "startedAt": "2023-11-07T05:31:56Z",
        "durationNs": "<string>",
        "text": "<string>",
        "audioUrl": "<string>",
        "toolName": "<string>",
        "toolArguments": "<string>",
        "toolResult": "<string>",
        "pov": "persona",
        "spans": "<array>",
        "toolProvenance": "mocked"
      }
    ],
    "spansTruncated": true
  }
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

GET

simulations

{simulationId}

Get a simulation

curl --request GET \
  --url https://app.egma.ai/v1/simulations/{simulationId} \
  --header 'Authorization: Bearer <token>'

{
  "id": "<string>",
  "projectId": "<string>",
  "runId": "<string>",
  "runName": "<string>",
  "position": 123,
  "status": "queued",
  "workBlock": {
    "error": "allowance_spent",
    "message": "<string>"
  },
  "gradingState": "not_requested",
  "evidenceError": {
    "error": "evidence_collection_error",
    "message": "<string>"
  },
  "grades": [
    {
      "projectGraderId": "<string>",
      "graderDefinitionId": "<string>",
      "graderDefinitionVersion": 2,
      "parameterValues": {},
      "graderName": "<string>",
      "score": 0.5,
      "details": {
        "rationale": "<string>",
        "assertions": [
          {
            "key": "<string>",
            "decision": "met",
            "score": 0.5,
            "rationale": "<string>",
            "citedSpanIds": [
              "<string>"
            ],
            "citedTurns": [
              2
            ],
            "error": "<string>"
          }
        ],
        "error": "<string>"
      },
      "passThreshold": 0.5,
      "result": "passed",
      "gradedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "gradeHistory": [
    {
      "projectGraderId": "<string>",
      "graderDefinitionId": "<string>",
      "graderDefinitionVersion": 2,
      "parameterValues": {},
      "graderName": "<string>",
      "score": 0.5,
      "details": {
        "rationale": "<string>",
        "assertions": [
          {
            "key": "<string>",
            "decision": "met",
            "score": 0.5,
            "rationale": "<string>",
            "citedSpanIds": [
              "<string>"
            ],
            "citedTurns": [
              2
            ],
            "error": "<string>"
          }
        ],
        "error": "<string>"
      },
      "passThreshold": 0.5,
      "result": "passed",
      "gradedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "combinedScore": 0.5,
  "reason": "<string>",
  "executionFailure": "<string>",
  "modality": "voice",
  "createdAt": "2023-11-07T05:31:56Z",
  "startedAt": "2023-11-07T05:31:56Z",
  "endedAt": "2023-11-07T05:31:56Z",
  "providerReference": "<string>",
  "hasRecording": true,
  "agentPovComplete": true,
  "agentPovIncomplete": true,
  "measures": {
    "durationMs": 123,
    "turnCount": 123,
    "toolCallCount": 123,
    "erroredStepCount": 123,
    "humanTurnCount": 123,
    "agentTurnCount": 123
  },
  "metrics": [
    {
      "measure": "<string>",
      "unit": "<string>",
      "derived": true,
      "pov": "persona",
      "samples": [
        123
      ],
      "spanIds": [
        "<string>"
      ],
      "mean": 123,
      "p50": 123,
      "p90": 123,
      "partial": true,
      "reportedBy": "<string>",
      "otherPov": {
        "pov": "persona",
        "derived": true,
        "samples": [
          123
        ],
        "spanIds": [
          "<string>"
        ],
        "partial": true,
        "reportedBy": "<string>"
      }
    }
  ],
  "test": {
    "id": "<string>",
    "versionId": "<string>",
    "name": "<string>",
    "scenario": "<string>",
    "expectedBehaviors": [
      "<string>"
    ]
  },
  "persona": {
    "id": "<string>",
    "name": "<string>",
    "versionId": "<string>",
    "identityName": "<string>",
    "personality": "<string>",
    "language": "<string>"
  },
  "agent": {
    "id": "<string>",
    "name": "<string>",
    "archived": true
  },
  "connection": {
    "id": "<string>",
    "name": "<string>",
    "archived": true
  },
  "connectionSnapshot": {
    "agentPlatform": "<string>",
    "connectionType": "<string>",
    "accessVariant": "<string>",
    "modality": "voice",
    "topology": "<string>",
    "environment": "<string>",
    "config": "<unknown>"
  },
  "gradingPlan": {
    "capturedAt": "2023-11-07T05:31:56Z",
    "items": [
      {
        "projectGraderId": "<string>",
        "graderDefinitionId": "<string>",
        "graderDefinitionVersion": 2,
        "graderName": "<string>",
        "passThreshold": 0.5
      }
    ]
  },
  "transcript": {
    "traceId": "<string>",
    "startedAt": "2023-11-07T05:31:56Z",
    "endedAt": "2023-11-07T05:31:56Z",
    "durationNs": "<string>",
    "spanCount": 123,
    "turnCounts": {
      "human": 123,
      "agent": 123
    },
    "toolSpanCount": 123,
    "erroredSpanCount": 123,
    "turns": [
      {
        "spanId": "<string>",
        "parentSpanId": "<string>",
        "name": "<string>",
        "kind": "<string>",
        "status": "<string>",
        "startedAt": "2023-11-07T05:31:56Z",
        "durationNs": "<string>",
        "text": "<string>",
        "audioUrl": "<string>",
        "toolName": "<string>",
        "toolArguments": "<string>",
        "toolResult": "<string>",
        "pov": "persona",
        "spans": "<array>",
        "toolProvenance": "mocked"
      }
    ],
    "spans": [
      {
        "spanId": "<string>",
        "parentSpanId": "<string>",
        "name": "<string>",
        "kind": "<string>",
        "status": "<string>",
        "startedAt": "2023-11-07T05:31:56Z",
        "durationNs": "<string>",
        "text": "<string>",
        "audioUrl": "<string>",
        "toolName": "<string>",
        "toolArguments": "<string>",
        "toolResult": "<string>",
        "pov": "persona",
        "spans": "<array>",
        "toolProvenance": "mocked"
      }
    ],
    "spansTruncated": true
  }
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

An Egma API key.

Path Parameters

simulationId

string

required

Simulation ID returned by List simulations in a run.

Minimum string length: 1

Example:

"sim_01M0E4J0BBE1FVDVTZ1BSS5C97"

Query Parameters

projectId

string

Minimum string length: 1

Response

The simulation and its available evidence. Check spansTruncated before treating the returned span tree as complete.

string

required

Minimum string length: 1

projectId

string

required

Minimum string length: 1

runId

string

required

Minimum string length: 1

runName

string | null

required

position

integer

required

status

enum<string>

required

Available options:

queued,

claimed,

running,

completed,

failed,

canceled

workBlock

object | null

required

Show child attributes

gradingState

enum<string> | null

required

Available options:

not_requested,

pending,

running,

complete,

error

evidenceError

object | null

required

Show child attributes

grades

object[]

required

The current result for each selected grader. Each grade has its own score, frozen threshold, result, and supporting details.

Show child attributes

gradeHistory

object[]

required

Recorded grade results, including previous grading attempts. Regrading preserves this history.

Show child attributes

combinedScore

number | null

required

Display-only arithmetic mean when every selected grader has a current score. Null while a required score is missing or errored. This is not an overall pass/fail result.

Required range: 0 <= x <= 1

reason

string | null

required

executionFailure

string | null

required

modality

enum<string>

required

Available options:

voice,

chat

createdAt

string<date-time>

required

startedAt

string<date-time> | null

required

endedAt

string<date-time> | null

required

providerReference

string | null

required

hasRecording

boolean

required

agentPovComplete

boolean

required

agentPovIncomplete

boolean

required

measures

object

required

Show child attributes

metrics

object[]

required

Observed facts about the conversation, such as latency and duration. Metrics are separate from grader results.

Show child attributes

test

object

required

Show child attributes

persona

object

required

Show child attributes

agent

object

required

Show child attributes

connection

object

required

Show child attributes

connectionSnapshot

object

required

Show child attributes

gradingPlan

object | null

required

The grader definitions, versions, and pass thresholds frozen when the run started. Regrading uses this selection.

Show child attributes

transcript

object | null

required

The conversation and tool evidence available for this simulation. Null when no trace is available.

Show child attributes

Runs

Agents

Connections

Test Suites

Tests

Personas

Simulations

Traces

Recordings

Graders

Monitoring

Repository

Projects

Organization

Members

API keys

Provider API keys

Get a simulation

Authorizations

Path Parameters

Query Parameters

Response