Skip to content

Assessments

The AI Readiness routes for assessments. 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.

Assess many semantic models in one run #

POST /v1/workspaces/{workspaceId}/aiReadiness/assess

Starts one assessment run over the semantic models the body names, at most 100, all in this workspace, and answers with the operation to ask about. The run is the one the BI Pixie portal starts from its picker: the whole run is counted against the day's assessments up front and refused whole when the allowance cannot cover it, every semantic model's name comes from Fabric, and each assessment is stored where the account keeps its results.

The run is accepted whole or not at all. A semantic model that is not in this workspace, or that the signed-in person cannot see, answers 404 ItemNotFound naming every such id in parameters; one BI Pixie maintains answers 400 OperationNotSupportedForItem the same way. Nothing is spent then.

The operation reports the run: it is Running with percentComplete as semantic models finish, and Succeeded when every one has an outcome. The outcomes are in the result, one row per semantic model, including the ones that were not assessed and why.

Scope
BIPixie.ReadWrite.All
Plan
Every plan
Counts against
Calls that start work, 30 a minute

Parameters

Parameters for Assess many semantic models in one run
Name In Type Required Description
workspaceId path string (uuid) Yes The id of the Fabric workspace.

Request body

JSON, BulkAssessRequest. The body is required.

Request body for Assess many semantic models in one run
Field Type Required Description
semanticModelIds array of string (uuid) Yes The semantic models to assess, all in the workspace in the path.

Responses

202. The run was started. The body carries the operation's id and address.

Headers of the 202 response to Assess many semantic models in one run
Header Description
Location Where to ask about the operation.
x-ms-operation-id
Retry-After Seconds to wait before asking for the operation's state.

To follow the work this call started, see Follow a long-running operation.

The 202 response to Assess many semantic models in one run, Accepted
Field Type Always present Description
operationId string (uuid) Yes The operation's id, which the operation's state and result take.
location string (uri) Yes Where to ask about the operation.

400. The request is not well formed, and nothing was started, changed or counted. errorCode is InvalidRequest, or InvalidPreview for a preview that is not available. A body member the operation does not document is refused this way, and the message names it and the documented member closest to it.

Headers of the 400 response to Assess many semantic models in one run
Header Description
x-ms-request-id The id of this request. Quote it to support.
The 400 response to Assess many semantic models in one run, ErrorResponse
Field Type Always present Description
errorCode string Yes Each code keeps its meaning once published. New codes can be added over time, and a code is never reused. One of InvalidRequest, InvalidPreview, PayloadTooLarge, BenchmarkQuestionsMissing, OperationNotSupportedForItem, Unauthorized, TokenExpired, InsufficientScopes, AppOnlyTokenNotSupported, UserNotRegistered, AccountNotActive, AdminRoleRequired, FeatureNotInPlan, FeatureTurnedOff, LicenseNotYours, TrackedItemLimitReached, LicenseTrackedItemLimitReached, FabricConsentRequired, FabricAccessDenied, WorkspaceNotFound, ItemNotFound, AssessmentNotFound, RunNotFound, AbTestNotFound, OperationNotFound, ScheduleNotFound, AiProviderNotFound, AiCredentialNotFound, OperationInProgress, OperationHasNoResult, ResultNotReady, ScheduleConflict, AiProviderConflict, ItemChanged, CapacityPaused, OperationExpired, RegionNotReady, CapacityRequired, CapacityUnpaid, StoreNotConnected, RequestBlocked, AssessmentDailyLimitReached, BenchmarkRunsExhausted, OptimizationApplyDailyLimitReached, FirstLookLimitReached, BenchmarkBuildLimitReached, FabricUnavailable, StoreUnavailable, ThrottleStoreUnavailable, UnknownError.
message string Yes
isRetriable boolean No
moreDetails array of object No
relatedResource object or null No
resourceId string No
resourceType string No
parameters array of object No
name string Yes
value string Yes
requestId string (uuid) Yes

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 POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "semanticModelIds": [
    "<uuid>"
  ]
}' \
  "https://api.bipixie.com/v1/workspaces/$WORKSPACE_ID/aiReadiness/assess"

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

Response, 202 
HTTP/1.1 202 Accepted
Content-Type: application/json
Location: https://api.bipixie.com/v1/operations/cd57b041-e44a-4dda-a4ff-02935ffb8c04
x-ms-operation-id: cd57b041-e44a-4dda-a4ff-02935ffb8c04
Retry-After: 5

{
  "operationId": "cd57b041-e44a-4dda-a4ff-02935ffb8c04",
  "location": "https://api.bipixie.com/v1/workspaces/e17c1b59-7a2e-491e-acdd-11434854bbb0/aiReadiness/assess"
}

Assess a semantic model #

POST /v1/workspaces/{workspaceId}/semanticModels/{semanticModelId}/aiReadiness/assess

Starts an assessment of a semantic model and answers with the operation to ask about. The request has no body. The assessment is the one the BI Pixie portal runs: it is counted against the day's assessments, it is stored where the account keeps its results, and it appears in the portal with every other assessment.

The first assessment of a semantic model is a first look. A later assessment of the same semantic model makes it a tracked item, and the operation's allowanceImpact says so.

BI Pixie looks up the workspace and the semantic model as the signed-in person before anything is counted. An id that person cannot see answers 404 or 403 and spends nothing.

The score is weighted by how the semantic model is used when the signed-in person has granted BI Pixie permission to read usage. When they have not, the assessment still runs without usage, and usage in the result says ConsentRequired, names the permission, says in message what the score is missing because of it, and links to the page where it is granted.

Scope
BIPixie.ReadWrite.All
Plan
Every plan
Counts against
Calls that start work, 30 a minute

Parameters

Parameters for Assess a semantic model
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

202. The assessment was started. The body carries the operation's id and address.

Headers of the 202 response to Assess a semantic model
Header Description
x-ms-request-id The id of this request. Quote it to support.
x-ms-operation-id The id of the operation.
Location The address of the operation's state.
Retry-After Seconds to wait before asking for the operation's state.

To follow the work this call started, see Follow a long-running operation.

The 202 response to Assess a semantic model, Accepted
Field Type Always present Description
operationId string (uuid) Yes The operation's id, which the operation's state and result take.
location string (uri) Yes Where to ask about the operation.

400. The request is not well formed, and nothing was started, changed or counted. errorCode is InvalidRequest, or InvalidPreview for a preview that is not available. A body member the operation does not document is refused this way, and the message names it and the documented member closest to it.

Headers of the 400 response to Assess a semantic model
Header Description
x-ms-request-id The id of this request. Quote it to support.
The 400 response to Assess a semantic model, ErrorResponse
Field Type Always present Description
errorCode string Yes Each code keeps its meaning once published. New codes can be added over time, and a code is never reused. One of InvalidRequest, InvalidPreview, PayloadTooLarge, BenchmarkQuestionsMissing, OperationNotSupportedForItem, Unauthorized, TokenExpired, InsufficientScopes, AppOnlyTokenNotSupported, UserNotRegistered, AccountNotActive, AdminRoleRequired, FeatureNotInPlan, FeatureTurnedOff, LicenseNotYours, TrackedItemLimitReached, LicenseTrackedItemLimitReached, FabricConsentRequired, FabricAccessDenied, WorkspaceNotFound, ItemNotFound, AssessmentNotFound, RunNotFound, AbTestNotFound, OperationNotFound, ScheduleNotFound, AiProviderNotFound, AiCredentialNotFound, OperationInProgress, OperationHasNoResult, ResultNotReady, ScheduleConflict, AiProviderConflict, ItemChanged, CapacityPaused, OperationExpired, RegionNotReady, CapacityRequired, CapacityUnpaid, StoreNotConnected, RequestBlocked, AssessmentDailyLimitReached, BenchmarkRunsExhausted, OptimizationApplyDailyLimitReached, FirstLookLimitReached, BenchmarkBuildLimitReached, FabricUnavailable, StoreUnavailable, ThrottleStoreUnavailable, UnknownError.
message string Yes
isRetriable boolean No
moreDetails array of object No
relatedResource object or null No
resourceId string No
resourceType string No
parameters array of object No
name string Yes
value string Yes
requestId string (uuid) Yes

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 POST \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.bipixie.com/v1/workspaces/$WORKSPACE_ID/semanticModels/$SEMANTIC_MODEL_ID/aiReadiness/assess"

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

Response, 202 
HTTP/1.1 202 Accepted
Content-Type: application/json
x-ms-request-id: cbf21b6d-b661-4b52-88cb-d79712e504fc
x-ms-operation-id: cd57b041-e44a-4dda-a4ff-02935ffb8c04
Location: https://api.bipixie.com/v1/operations/cd57b041-e44a-4dda-a4ff-02935ffb8c04
Retry-After: 5

{
  "operationId": "cd57b041-e44a-4dda-a4ff-02935ffb8c04",
  "location": "https://api.bipixie.com/v1/workspaces/e17c1b59-7a2e-491e-acdd-11434854bbb0/semanticModels/f1fdc461-3ca1-4702-ae48-afc3522409fc/aiReadiness/assess"
}

List the assessments of a semantic model #

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

Returns the stored assessments of a semantic model, newest first. Each one says whether it can be compared with the assessment before it. A semantic model with no stored assessment answers an empty list.

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

Parameters

Parameters for List the assessments of a semantic model
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.
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 assessments.

Headers of the 200 response to List the assessments of a semantic model
Header Description
x-ms-request-id The id of this request. Quote it to support.
The 200 response to List the assessments of a semantic model, AssessmentList
Field Type Always present Description
value array of AssessmentSummary Yes
assessmentId string Yes
assessedAtUtc string or null (date-time) No
score number or null No
scoreDataAgent number or null No
findingsCount integer or null No
regimeId string Yes
usageInScoring boolean or null No Whether the way the semantic model is used took part in the score.
comparableWithPrevious boolean No Whether this assessment and the one before it were produced by the same scoring rules. False for the first assessment.
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/workspaces/$WORKSPACE_ID/semanticModels/$SEMANTIC_MODEL_ID/aiReadiness/assessments"

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": [
    {
      "assessmentId": "63654520-134e-4565-8a3f-030a1ae0eba7",
      "assessedAtUtc": "2026-09-14T09:30:05Z",
      "score": 78,
      "scoreDataAgent": 78,
      "findingsCount": 12,
      "regimeId": "aa6d9e39-ee9e-46d8-a9d4-089f050ea78e",
      "usageInScoring": true,
      "comparableWithPrevious": true
    }
  ],
  "continuationToken": "eyJza2lwIjoxMDB9",
  "continuationUri": "https://api.bipixie.com/v1/workspaces/e17c1b59-7a2e-491e-acdd-11434854bbb0/semanticModels/f1fdc461-3ca1-4702-ae48-afc3522409fc/aiReadiness/assessments?continuationToken=eyJza2lwIjoxMDB9"
}

Get an assessment #

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

Returns one stored assessment, whole. The assessment is read from where the account keeps its results. An id that is not an assessment of this semantic model in this account answers 404.

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

Parameters

Parameters for Get an assessment
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.
assessmentId path string Yes The assessmentId from a list of assessments or from a result.

Responses

200. The assessment.

Headers of the 200 response to Get an assessment
Header Description
x-ms-request-id The id of this request. Quote it to support.
The 200 response to Get an assessment, Assessment
Field Type Always present Description
assessmentId string or null Yes The id of the stored assessment. Null when the assessment was not stored.
workspaceId string or null No
workspaceName string or null No
semanticModelId string or null Yes
semanticModelName string or null No
assessedAtUtc string or null (date-time) No When the assessment was taken. Null when the assessment was not stored.
score number or null Yes The AI Readiness score, from 0 to 100.
scoreDataAgent number or null No The score as a data agent reads the semantic model.
findingsCount integer or null Yes
usage object Yes Whether the way the semantic model is used weighted the score.
applied boolean Yes Whether the account had usage to weight the score with.
state string or null No
reason string or null No
windowDays integer or null No The number of days of usage the score was measured over.
trackedReportCount integer or null No
access string No Whether BI Pixie could read usage as the signed-in person. Granted, ConsentRequired when the person has not granted the permission, or Unavailable when Microsoft did not answer. Present on the result of an operation, which is where it is known. One of Granted, ConsentRequired, Unavailable.
permission string No The permission usage is read with, Dataset.Read.All. Present with ConsentRequired and Unavailable.
message string No Why usage was not read, what the score is missing because of it, and what to do. Present with ConsentRequired and Unavailable.
consentUrl string (uri) No Where the permission is granted. Present with ConsentRequired. Its grant query parameter names the permission.
regime object Yes Which scoring rules produced the score. Two scores are comparable only when their id is the same.
id string Yes
usageInScoring boolean or null No
comparableWithPrevious boolean No True when an earlier assessment of this semantic model exists and was produced by the same scoring rules. False otherwise, including for the first assessment.
stored object Yes
location string Yes Where the assessment is kept. BIPixie, CustomerOneLake or CustomerStorage for an account that keeps its results in its own storage, Unknown when that could not be read, and None when the assessment was not stored. One of BIPixie, CustomerOneLake, CustomerStorage, Unknown, None.
reason string or null No Why the assessment was not stored.
deliveryPending boolean Yes Whether the assessment is waiting to be delivered to the account's own storage.
document object Yes The assessment as stored. report.overall_score, report.dimensions and report.findings hold the score, the score of each dimension and the findings. A finding has no id. Its key is its dimension, table and object_name together.
schemaVersion integer Yes

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/assessments/$ASSESSMENT_ID"

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

{
  "assessmentId": "63654520-134e-4565-8a3f-030a1ae0eba7",
  "workspaceId": "e17c1b59-7a2e-491e-acdd-11434854bbb0",
  "workspaceName": "Contoso Sales Analytics",
  "semanticModelId": "f1fdc461-3ca1-4702-ae48-afc3522409fc",
  "semanticModelName": "Contoso Sales",
  "assessedAtUtc": "2026-09-14T09:30:05Z",
  "score": 78,
  "scoreDataAgent": 78,
  "findingsCount": 12,
  "usage": {
    "applied": true,
    "state": "available",
    "reason": "Not available for this item.",
    "windowDays": 28,
    "trackedReportCount": 12,
    "access": "Granted",
    "permission": "ConsentRequired",
    "message": "ConsentRequired",
    "consentUrl": "https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize?client_id=ebc40edd-1874-4e14-a1e5-e21b45f6286a&response_type=code"
  },
  "regime": {
    "id": "3f4bc9c2-b27e-49df-9de1-a78801b93655",
    "usageInScoring": true,
    "comparableWithPrevious": true
  },
  "stored": {
    "location": "BIPixie",
    "reason": "Not available for this item.",
    "deliveryPending": true
  },
  "document": {
    "schemaVersion": 3
  }
}

What's next