Semantic models

The AI Readiness routes for semantic models. The other areas are listed on the AI Readiness reference.

Every route below follows the conventions in Work with the BI Pixie API. You can also download the OpenAPI document.

List semantic models #

GET /v1/aiReadiness/semanticModels

Returns one row for each semantic model the account has assessed or benchmarked, with its latest score, the change since the assessment before it, whether it is a tracked item, and its latest benchmark. The numbers are the ones the BI Pixie portal shows.

scoreChange is given only when the two scores were produced by the same scoring rules. When they were not, comparableWithPrevious is false and both scores are in the row.

Scope: BIPixie.Read.All
Plan: Every plan
Counts against: Calls that read, 300 a minute

Parameters

Parameters for List semantic models
Name	In	Type	Required	Description
`q`	query	string	No	Return only semantic models whose name, workspace name or id contains this text.
`workspaceId`	query	string (uuid)	No	Return only semantic models in this workspace.
`sort`	query	string	No	The order of the list. The lowest score comes first by default. One of `ScoreAscending`, `ScoreDescending`, `BenchmarkAscending`, `BenchmarkDescending`, `AssessedNewest`, `AssessedOldest`, `BenchmarkNewest`, `BenchmarkOldest`, `NameAscending`, `NameDescending`.
`maxResults`	query	integer	No	The largest number of rows to return in one page.
`continuationToken`	query	string	No	The token the previous page answered with.

Responses

200. One page of semantic models.

Headers of the 200 response to List semantic models
Header	Description
`x-ms-request-id`	The id of this request. Quote it to support.

The 200 response to List semantic models, SemanticModelList
Field	Type	Always present	Description
`value`	array of SemanticModel	Yes
`semanticModelId`	string or null	Yes
`semanticModelName`	string or null	No
`workspaceId`	string or null	No
`workspaceName`	string or null	No
`score`	number or null	No	The latest AI Readiness score, from 0 to 100.
`scoreDataAgent`	number or null	No
`previousScore`	number or null	No	The score of the assessment before the latest one.
`scoreChange`	number or null	No	`score` less `previousScore`. Null when there is no previous score, and when the two were produced by different scoring rules.
`comparableWithPrevious`	boolean	No	Whether the two scores were produced by the same scoring rules. False when there is no previous score.
`regimeId`	string	Yes	Which scoring rules produced `score`.
`assessmentCount`	integer	Yes
`lastAssessedAtUtc`	string or null (date-time)	No
`latestAssessmentId`	string or null	No
`tracked`	boolean	Yes	Whether the semantic model is a tracked item.
`maintainedByBIPixie`	boolean	No	Whether this is the semantic model of the BI Pixie dashboard. BI Pixie maintains it, so it is not assessed or benchmarked.
`optimization`	object	No
`count`	integer	No	How many applies BI Pixie has made to this semantic model toward readiness, INCLUDING ones later put back. A revert is not counted, so this number never falls; read `standing` to learn whether the latest one still stands.
`lastAtUtc`	string or null (date-time)	No	When the latest apply landed. Unchanged by a revert.
`standing`	string or null	No	Whether the latest recorded apply still stands. `Reverted` when it was put back and nothing was applied since; `Applied` otherwise. Null when no apply was ever recorded, which is not the same as one that was undone. A semantic model whose change was reverted before 2026-10-06 reads `Applied`, because reverts were recorded nowhere until then. One of `Applied`, `Reverted`, `null`.
`lastRevertedAtUtc`	string or null (date-time)	No	When an apply to this semantic model was last put back. Null when none was, and null on a revert made before 2026-10-06.
`benchmark`	object	Yes
`runCount`	integer	Yes
`passRate`	number or null	No	The share of benchmark questions answered correctly in every repeat of the latest run, out of every question it asked, from 0 to 1. Null when the run scored nothing. A question that was not scored counts as not answered correctly, so read it with `scored` and `notScored`.
`stable`	integer or null	No
`scored`	integer or null	No
`notScored`	integer or null	No	How many of the latest run's questions were not scored. Null when the run's counts were not recorded.
`total`	integer or null	No
`lastRunAtUtc`	string or null (date-time)	No
`answeredBy`	string or null	No
`dataAgentName`	string or null	No
`running`	boolean	Yes	Whether a benchmark is running for this semantic model now.
`continuationToken`	string	No
`continuationUri`	string (uri)	No

Errors

Every refusal is an ErrorResponse with a stable errorCode. See Errors for what each HTTP status means and every code the API can return.

This is an example of a refusal. Every refusal has the same fields.

Example refusal

HTTP/1.1 404 Not Found
Content-Type: application/json
x-ms-request-id: cbf21b6d-b661-4b52-88cb-d79712e504fc

{
  "errorCode": "ItemNotFound",
  "message": "No item with this id is visible to the signed-in person in this workspace, or it is not of the type the route takes.",
  "isRetriable": false,
  "moreDetails": [],
  "relatedResource": {
    "resourceId": "d972b3f5-a2fa-47ec-94ff-0403a4d159fa",
    "resourceType": "SemanticModel"
  },
  "parameters": [
    {
      "name": "itemId",
      "value": "d972b3f5-a2fa-47ec-94ff-0403a4d159fa"
    }
  ],
  "requestId": "cbf21b6d-b661-4b52-88cb-d79712e504fc"
}

Example

Request

curl -i -X GET \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.bipixie.com/v1/aiReadiness/semanticModels"

An example of what the call answers. The values are fictional.

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
x-ms-request-id: cbf21b6d-b661-4b52-88cb-d79712e504fc

{
  "value": [
    {
      "semanticModelId": "f1fdc461-3ca1-4702-ae48-afc3522409fc",
      "semanticModelName": "Contoso Sales",
      "workspaceId": "e17c1b59-7a2e-491e-acdd-11434854bbb0",
      "workspaceName": "Contoso Sales Analytics",
      "score": 78,
      "scoreDataAgent": 78,
      "previousScore": 74,
      "scoreChange": 4,
      "comparableWithPrevious": true,
      "regimeId": "aa6d9e39-ee9e-46d8-a9d4-089f050ea78e",
      "assessmentCount": 12,
      "lastAssessedAtUtc": "2026-09-14T09:42:17Z",
      "latestAssessmentId": "8c801b5b-a3d8-4166-9dfe-ceb1a3ecf1f4",
      "tracked": true,
      "maintainedByBIPixie": true,
      "optimization": {
        "count": 12,
        "lastAtUtc": "2026-09-14T09:42:17Z",
        "standing": "Applied",
        "lastRevertedAtUtc": "2026-09-14T09:42:17Z"
      },
      "benchmark": {
        "runCount": 12,
        "passRate": 0.75,
        "stable": 3,
        "scored": 12,
        "notScored": 78,
        "total": 12,
        "lastRunAtUtc": "2026-09-14T09:42:17Z",
        "answeredBy": "fabric_data_agent",
        "dataAgentName": "Contoso Sales Agent",
        "running": true
      }
    }
  ],
  "continuationToken": "eyJza2lwIjoxMDB9",
  "continuationUri": "https://api.bipixie.com/v1/aiReadiness/semanticModels?continuationToken=eyJza2lwIjoxMDB9"
}

Get a semantic model's AI Readiness in one call #

GET /v1/workspaces/{workspaceId}/semanticModels/{semanticModelId}/aiReadiness

Returns what the portal's semantic model page shows, in one call: the registry's row for the semantic model, its latest assessment as the assessments list describes it, the data agents grounded on it, the AI provider BI Pixie would write for it with, and where its assessments are. A semantic model BI Pixie has no record of in this account, neither assessed nor benchmarked, answers 404; one benchmarked but never assessed answers with a null score.

Scope: BIPixie.Read.All
Plan: Every plan
Counts against: Calls that read, 300 a minute

Parameters

Parameters for Get a semantic model's AI Readiness in one call
Name	In	Type	Required	Description
`workspaceId`	path	string (uuid)	Yes	The id of the Fabric workspace.
`semanticModelId`	path	string (uuid)	Yes	The id of the semantic model in that workspace.

Responses

200. The semantic model's AI Readiness.

Headers of the 200 response to Get a semantic model's AI Readiness in one call
Header	Description
`x-ms-request-id`	The id of this request. Quote it to support.

The 200 response to Get a semantic model's AI Readiness in one call, SemanticModelReadiness
Field	Type	Always present	Description
`semanticModelId`	string or null	Yes
`semanticModelName`	string or null	No
`workspaceId`	string or null	No
`workspaceName`	string or null	No
`score`	number or null	No	The latest AI Readiness score, from 0 to 100.
`scoreDataAgent`	number or null	No
`previousScore`	number or null	No	The score of the assessment before the latest one.
`scoreChange`	number or null	No	`score` less `previousScore`. Null when there is no previous score, and when the two were produced by different scoring rules.
`comparableWithPrevious`	boolean	No	Whether the two scores were produced by the same scoring rules. False when there is no previous score.
`regimeId`	string	Yes	Which scoring rules produced `score`.
`assessmentCount`	integer	Yes
`lastAssessedAtUtc`	string or null (date-time)	No
`latestAssessmentId`	string or null	No
`tracked`	boolean	Yes	Whether the semantic model is a tracked item.
`maintainedByBIPixie`	boolean	No	Whether this is the semantic model of the BI Pixie dashboard. BI Pixie maintains it, so it is not assessed or benchmarked.
`optimization`	object	No
`count`	integer	No	How many applies BI Pixie has made to this semantic model toward readiness, INCLUDING ones later put back. A revert is not counted, so this number never falls; read `standing` to learn whether the latest one still stands.
`lastAtUtc`	string or null (date-time)	No	When the latest apply landed. Unchanged by a revert.
`standing`	string or null	No	Whether the latest recorded apply still stands. `Reverted` when it was put back and nothing was applied since; `Applied` otherwise. Null when no apply was ever recorded, which is not the same as one that was undone. A semantic model whose change was reverted before 2026-10-06 reads `Applied`, because reverts were recorded nowhere until then. One of `Applied`, `Reverted`, `null`.
`lastRevertedAtUtc`	string or null (date-time)	No	When an apply to this semantic model was last put back. Null when none was, and null on a revert made before 2026-10-06.
`benchmark`	object	Yes
`runCount`	integer	Yes
`passRate`	number or null	No	The share of benchmark questions answered correctly in every repeat of the latest run, out of every question it asked, from 0 to 1. Null when the run scored nothing. A question that was not scored counts as not answered correctly, so read it with `scored` and `notScored`.
`stable`	integer or null	No
`scored`	integer or null	No
`notScored`	integer or null	No	How many of the latest run's questions were not scored. Null when the run's counts were not recorded.
`total`	integer or null	No
`lastRunAtUtc`	string or null (date-time)	No
`answeredBy`	string or null	No
`dataAgentName`	string or null	No
`running`	boolean	Yes	Whether a benchmark is running for this semantic model now.
`latestAssessment`	one of AssessmentSummary, null	No
`dataAgents`	array of DataAgentSummary	Yes	The data agents grounded on this semantic model, worst first.
`dataAgentId`	string or null	Yes
`displayName`	string or null	No
`workspaceId`	string or null	No
`score`	number or null	No
`findingsCount`	integer	No
`regimeId`	string	Yes
`lastAssessedAtUtc`	string or null (date-time)	No
`aiProvider`	one of AiProvider, null	No
`links`	ReadinessLinks	Yes
`assessments`	string (uri)	Yes	Where the item's assessments are listed.
`assess`	string (uri)	Yes	Where an assessment of the item is started, with POST.
`abTests`	string (uri)	Yes	Where the A/B tests the item is a side of are listed.

Errors

Every refusal is an ErrorResponse with a stable errorCode. See Errors for what each HTTP status means and every code the API can return.

This is an example of a refusal. Every refusal has the same fields.

Example refusal

HTTP/1.1 404 Not Found
Content-Type: application/json
x-ms-request-id: cbf21b6d-b661-4b52-88cb-d79712e504fc

{
  "errorCode": "ItemNotFound",
  "message": "No item with this id is visible to the signed-in person in this workspace, or it is not of the type the route takes.",
  "isRetriable": false,
  "moreDetails": [],
  "relatedResource": {
    "resourceId": "d972b3f5-a2fa-47ec-94ff-0403a4d159fa",
    "resourceType": "SemanticModel"
  },
  "parameters": [
    {
      "name": "itemId",
      "value": "d972b3f5-a2fa-47ec-94ff-0403a4d159fa"
    }
  ],
  "requestId": "cbf21b6d-b661-4b52-88cb-d79712e504fc"
}

Example

Request

curl -i -X GET \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.bipixie.com/v1/workspaces/$WORKSPACE_ID/semanticModels/$SEMANTIC_MODEL_ID/aiReadiness"

An example of what the call answers. The values are fictional.

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
x-ms-request-id: cbf21b6d-b661-4b52-88cb-d79712e504fc

{
  "semanticModelId": "f1fdc461-3ca1-4702-ae48-afc3522409fc",
  "semanticModelName": "Contoso Sales",
  "workspaceId": "e17c1b59-7a2e-491e-acdd-11434854bbb0",
  "workspaceName": "Contoso Sales Analytics",
  "score": 78,
  "scoreDataAgent": 78,
  "previousScore": 74,
  "scoreChange": 4,
  "comparableWithPrevious": true,
  "regimeId": "aa6d9e39-ee9e-46d8-a9d4-089f050ea78e",
  "assessmentCount": 12,
  "lastAssessedAtUtc": "2026-09-14T09:42:17Z",
  "latestAssessmentId": "8c801b5b-a3d8-4166-9dfe-ceb1a3ecf1f4",
  "tracked": true,
  "maintainedByBIPixie": true,
  "optimization": {
    "count": 12,
    "lastAtUtc": "2026-09-14T09:42:17Z",
    "standing": "Applied",
    "lastRevertedAtUtc": "2026-09-14T09:42:17Z"
  },
  "benchmark": {
    "runCount": 12,
    "passRate": 0.75,
    "stable": 3,
    "scored": 12,
    "notScored": 78,
    "total": 12,
    "lastRunAtUtc": "2026-09-14T09:42:17Z",
    "answeredBy": "fabric_data_agent",
    "dataAgentName": "Contoso Sales Agent",
    "running": true
  },
  "latestAssessment": null,
  "dataAgents": [
    {
      "dataAgentId": "05dd87d1-624f-4ffa-ab88-ee231a75a904",
      "displayName": "Contoso Sales",
      "workspaceId": "e17c1b59-7a2e-491e-acdd-11434854bbb0",
      "score": 78,
      "findingsCount": 12,
      "regimeId": "aa6d9e39-ee9e-46d8-a9d4-089f050ea78e",
      "lastAssessedAtUtc": "2026-09-14T09:42:17Z"
    }
  ],
  "aiProvider": null,
  "links": {
    "assessments": "https://api.bipixie.com/v1/workspaces/e17c1b59-7a2e-491e-acdd-11434854bbb0/semanticModels/f1fdc461-3ca1-4702-ae48-afc3522409fc/aiReadiness/assessments",
    "assess": "https://api.bipixie.com/v1/workspaces/e17c1b59-7a2e-491e-acdd-11434854bbb0/semanticModels/f1fdc461-3ca1-4702-ae48-afc3522409fc/aiReadiness/assess",
    "abTests": "https://api.bipixie.com/v1/workspaces/e17c1b59-7a2e-491e-acdd-11434854bbb0/semanticModels/f1fdc461-3ca1-4702-ae48-afc3522409fc/abTests"
  }
}

Semantic models

List semantic models #

Parameters

Responses

Errors

Example

Get a semantic model's AI Readiness in one call #

Parameters

Responses

Errors

Example

What's next