List Versions

GEThttps://api.confident-ai.com/v2/organization/governance-controls/{controlId}/versions

Lists a governance control's definition history, newest version first, so the first entry is the rule the control evaluates today. Versions are append-only, which makes this the record of how the check has changed and which definition each past verdict was computed against — pass a version's version label to the assessments endpoint to read the verdicts it produced.

GET/v2/organization/governance-controls/{controlId}/versions

curl -X GET "https://api.confident-ai.com/v2/organization/governance-controls/{controlId}/versions" \
  -H "CONFIDENT_API_KEY: <ORGANIZATION-API-KEY>"

200

{
  "success": true,
  "data": {
    "versions": [
      {
        "id": "<GOVERNANCE-CONTROL-VERSION-ID>",
        "version": "00.00.02",
        "sequence": 2,
        "dataModel": "TRACE",
        "aggregation": "Error rate",
        "thresholdSettings": {
          "value": 0.02,
          "direction": "above"
        },
        "extraQueryParams": {
          "category": "TRACE"
        },
        "preDeploymentSettings": {
          "identifier": "pre-release",
          "window": {
            "days": 30
          },
          "officialOnly": false
        },
        "filters": {
          "operator": "AND",
          "groups": [
            {
              "operator": "AND",
              "filters": [
                {
                  "category": "User Id",
                  "condition": "Is less than",
                  "value": "string",
                  "key": "string"
                }
              ]
            }
          ]
        },
        "severity": "CRITICAL",
        "assessmentsCount": 64,
        "createdAt": "2025-01-18T16:45:00.000Z"
      }
    ],
    "totalGovernanceControlVersions": 2,
    "page": 1,
    "pageSize": 25
  },
  "link": "https://app.confident-ai.com/organization/<ORGANIZATION-ID>/governance/controls/<GOVERNANCE-CONTROL-ID>",
  "deprecated": false
}

Headers

CONFIDENT_API_KEYstringRequired
The organization API key for your Confident AI organization.

Path parameters

controlIdstringRequired
The id of the governance control.

Query parameters

pageintegerdefault: 1
The page to return. Defaults to 1.
pageSizeintegerdefault: 25
The number of versions per page, at most 100. Defaults to 25.

Response

List Versions succeeded.

successboolean
Indicates if the request was successful.
dataobject
One page of a control's definition history, with the total across all pages.
Show 4 propertiesHide 4 properties
- versionslist of objects
  The control's definition history for the current page, newest version first, so the first entry of the first page is the current definition.
  Show 12 propertiesHide 12 properties
  - idstring
    The id of the version, generated by Confident AI.
  - versionstring
    The human-readable label for sequence, written as three two-digit groups that roll over at 100, so sequence 2 is 00.00.02 and sequence 100 is 00.01.00.
  - sequenceinteger
    The position of this version in the control's history, counting from 1. The highest sequence is the current version, which is the one every new assessment runs against.
  - dataModelenum | null
    The production data a runtime control measures: TRACE for whole requests, SPAN for individual steps, THREAD for conversations, METRIC_DATA for evaluation scores, and ANNOTATION for human ratings. It decides which aggregations are valid.
    Show 5 enum valuesHide 5 enum values
    TRACE
    SPAN
    THREAD
    METRIC_DATA
    ANNOTATION
  - aggregationstring | null
    How the measured data is reduced to one number, as one of the GovernanceControlAggregation values. It is set on a runtime control and null on every other type.
  - thresholdSettingsobject | null
    A threshold as a version stores it. Both fields are set on a configured runtime control; either can be absent on a version snapshotted before the control was configured, which is what makes it unconfigured.
    Show 2 propertiesHide 2 properties
    valuenumber
    The number the aggregated value is compared against, in the unit the aggregation produces — a rate is a fraction between 0 and 1, a latency is in milliseconds, a cost is in USD.
    directionenum
    Which side of the threshold fails: above fails once the measured value rises past value, below fails once it drops under it.
    Show 2 enum valuesHide 2 enum values
    above
    below
  - extraQueryParamsobject | null
    Extra scoping for the data a runtime control measures, beyond its data model and filters.
    Show 1 propertyHide 1 property
    categoryenum
    Which kind of item the evaluation scores were recorded on, for a control measuring METRIC_DATA.
    Show 3 enum valuesHide 3 enum values
    TRACE
    SPAN
    THREAD
  - preDeploymentSettingsobject | null
    Which run a pre-deployment control gates on. The fields are individually optional because a version snapshotted before the control was configured stores an empty object; a configured control always carries either identifier and window or officialOnly set to true.
    Show 3 propertiesHide 3 properties
    identifierstring
    The identifier of the test run or red teaming run the control gates on. Absent on a control that gates on the project's official run instead.
    windowobject
    The rolling lookback a pre-deployment control searches for the run it gates on.
    Show 1 propertyHide 1 property
    daysinteger
    How many days back the control looks for a run. It is stored as a day count rather than as dates, so the gate does not go stale as it is re-assessed.
    officialOnlyboolean
    Whether the control gates on the project's most recent official run rather than on a run matching identifier.
  - filtersobject | null
    A set of filter groups combined by a top-level operator. Each group combines its filter rows by its own operator, and each row matches one property, such as Name or User Id, against a value with a condition such as Is or Contains.
    Show 2 propertiesHide 2 properties
    operatorenum
    Show 2 enum valuesHide 2 enum values
    AND
    OR
    groupslist of objects
    Show 2 propertiesHide 2 properties
    operatorenum
    Show 2 enum valuesHide 2 enum values
    AND
    OR
    filterslist of objects
    Show 4 propertiesHide 4 properties
    categoryenum
    Show 80 enum valuesHide 80 enum values
    User Id
    Thread Id
    Trace Uuid
    Trace Name
    Trace Version
    Trace Status
    Trace Tags
    Trace
    Span Uuid
    Name
    Span Name
    Span Type
    Span Status
    Metrics Status
    Error Status
    Name
    Model
    Provider
    Integration
    Embedder
    Chunk Size
    Top-K
    Hyperparameter
    Dataset
    Dataset Name
    Test Run ID
    Identifier
    Test File
    Status
    Official
    Evals Mode
    Tests Passed
    Tests Failed
    Pass Rate
    Fail Rate
    Star Rating
    Thumbs Rating
    Explanation
    Expected Output
    Expected Outcome
    Annotator
    End User
    Annotation Type
    Annotation Name
    Criteria
    Annotation Date
    Metric Score
    Metric Status
    Name
    Metadata
    Classifier
    Metric
    Metric Name
    Trace Count
    Test Case ID
    Requested review from
    Assigned to
    Tags
    Labels
    Tools Called
    Finalized
    Golden ID
    Ingestion Task
    Latency
    Environment
    Review flag
    Vulnerability
    Vulnerability Type
    Attack Method
    Risk Category
    Framework
    Assessment ID
    Prompt Alias
    Prompt Version
    Prompt Label
    Prompt Commit Hash
    Prompt
    Annotations
    Status Code
    Actor Type
    conditionenum | enum | enum | enum | enum | enum | enum | enum | enum | enum
    valuestring | number | list of strings
    keystring
  - severityenum | null
    How much a failing control matters, set per version rather than per control. LOW never blocks a deployment gate; CRITICAL, HIGH and MEDIUM block, and so does leaving the severity unset.
    Show 4 enum valuesHide 4 enum values
    CRITICAL
    HIGH
    MEDIUM
    LOW
  - assessmentsCountinteger
    How many verdicts were recorded against this version.
  - createdAtstring
    When this version was snapshotted.
- totalGovernanceControlVersionsinteger
  The number of versions this control has, across every page.
- pageinteger
  The page this response covers.
- pageSizeinteger
  The number of versions per page.
linkstring
This is the URL of the resource on the Confident AI platform.
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI