Skip to content

Data agents

The AI Readiness routes for data agents. 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 the data agents the account has assessed #

GET /v1/aiReadiness/dataAgents

Returns one row for each data agent the account has assessed, with its latest score, the change since the assessment before it, what it is grounded on and whether the latest assessment could read each item, and its latest benchmark. The lowest score comes first by default. The list is paged.

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

Parameters

Parameters for List the data agents the account has assessed
Name In Type Required Description
q query string No Return only data agents whose name, workspace name or id contains this text.
workspaceId query string (uuid) No Return only data agents 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 data agents.

Headers of the 200 response to List the data agents the account has assessed
Header Description
x-ms-request-id The id of this request. Quote it to support.
The 200 response to List the data agents the account has assessed, DataAgentList
Field Type Always present Description
value array of DataAgent Yes
dataAgentId string or null Yes
displayName 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.
previousScore number or null No The score of the assessment before the latest one.
scoreChange number or null No score less previousScore, as the portal prints it: between the two newest assessments whatever scoring rules produced them. Null when there is no previous score.
regimeId string Yes The scoring rules that produced score.
scoredRounds integer Yes 1 when only the deterministic round scored; 2 when an AI round did too. One of 1, 2.
findingsCount integer No
publishState string or null No
previewRuntime boolean No Whether the data agent runs on the preview runtime.
assessmentCount integer Yes
lastAssessedAtUtc string or null (date-time) No
latestAssessmentId string or null No
groundedOn array of GroundingSource Yes The items the data agent is grounded on, as its latest assessment found them.
itemId string or null No
itemType string or null No Fabric's item type where one exists (SemanticModel, Lakehouse, Warehouse, KQLDatabase, MirroredDatabase, SQLDatabase, MirroredAzureDatabricksCatalog), else BI Pixie's own name for the source.
displayName string or null No
workspaceId string or null No
assessed boolean Yes Whether the latest assessment could read this item. A warehouse or a mirrored database is read only with the storage permission.
optimization object Yes
count integer Yes How many applies BI Pixie has made to this data agent 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 data agent 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 data agent 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 latest run's correct answers out of all its questions, from 0 to 1. A question that was not scored counts as not answered correctly, so read it with scored and notScored.
scored integer or null No How many of the latest run's questions reached a verdict. Null when the run's counts were not recorded.
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.
passRateChange number or null No The change against the run before, present only when that run asked about the same semantic model.
semanticModelId string or null No The semantic model the latest run asked about.
semanticModelName string or null No
lastRunAtUtc string or null (date-time) No
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/dataAgents"

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": [
    {
      "dataAgentId": "05dd87d1-624f-4ffa-ab88-ee231a75a904",
      "displayName": "Contoso Sales",
      "workspaceId": "e17c1b59-7a2e-491e-acdd-11434854bbb0",
      "workspaceName": "Contoso Sales Analytics",
      "score": 78,
      "previousScore": 74,
      "scoreChange": 4,
      "regimeId": "aa6d9e39-ee9e-46d8-a9d4-089f050ea78e",
      "scoredRounds": 1,
      "findingsCount": 12,
      "publishState": "Published",
      "previewRuntime": true,
      "assessmentCount": 12,
      "lastAssessedAtUtc": "2026-09-14T09:42:17Z",
      "latestAssessmentId": "8c801b5b-a3d8-4166-9dfe-ceb1a3ecf1f4",
      "groundedOn": [
        {
          "itemId": "d972b3f5-a2fa-47ec-94ff-0403a4d159fa",
          "itemType": "SemanticModel",
          "displayName": "Contoso Sales",
          "workspaceId": "e17c1b59-7a2e-491e-acdd-11434854bbb0",
          "assessed": true
        }
      ],
      "optimization": {
        "count": 12,
        "lastAtUtc": "2026-09-14T09:42:17Z",
        "standing": "Applied",
        "lastRevertedAtUtc": "2026-09-14T09:42:17Z"
      },
      "benchmark": {
        "runCount": 12,
        "passRate": 0.75,
        "scored": 12,
        "notScored": 78,
        "passRateChange": 0.05,
        "semanticModelId": "f1fdc461-3ca1-4702-ae48-afc3522409fc",
        "semanticModelName": "Contoso Sales",
        "lastRunAtUtc": "2026-09-14T09:42:17Z"
      }
    }
  ],
  "continuationToken": "eyJza2lwIjoxMDB9",
  "continuationUri": "https://api.bipixie.com/v1/aiReadiness/dataAgents?continuationToken=eyJza2lwIjoxMDB9"
}

Get a data agent's AI Readiness in one call #

GET /v1/workspaces/{workspaceId}/dataAgents/{dataAgentId}/aiReadiness

Returns what the portal's data agent page shows, in one call: the registry's row for the data agent, which names what it is grounded on and its latest assessment, the AI provider BI Pixie would write for it with, and where its assessments are. A data agent BI Pixie has no record of in this account, neither assessed nor created through BI Pixie, answers 404; one created 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 data agent's AI Readiness in one call
Name In Type Required Description
workspaceId path string (uuid) Yes The id of the Fabric workspace.
dataAgentId path string (uuid) Yes The id of the data agent in that workspace.

Responses

200. The data agent's AI Readiness.

Headers of the 200 response to Get a data agent'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 data agent's AI Readiness in one call, DataAgentReadiness
Field Type Always present Description
dataAgentId string or null Yes
displayName 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.
previousScore number or null No The score of the assessment before the latest one.
scoreChange number or null No score less previousScore, as the portal prints it: between the two newest assessments whatever scoring rules produced them. Null when there is no previous score.
regimeId string Yes The scoring rules that produced score.
scoredRounds integer Yes 1 when only the deterministic round scored; 2 when an AI round did too. One of 1, 2.
findingsCount integer No
publishState string or null No
previewRuntime boolean No Whether the data agent runs on the preview runtime.
assessmentCount integer Yes
lastAssessedAtUtc string or null (date-time) No
latestAssessmentId string or null No
groundedOn array of GroundingSource Yes The items the data agent is grounded on, as its latest assessment found them.
itemId string or null No
itemType string or null No Fabric's item type where one exists (SemanticModel, Lakehouse, Warehouse, KQLDatabase, MirroredDatabase, SQLDatabase, MirroredAzureDatabricksCatalog), else BI Pixie's own name for the source.
displayName string or null No
workspaceId string or null No
assessed boolean Yes Whether the latest assessment could read this item. A warehouse or a mirrored database is read only with the storage permission.
optimization object Yes
count integer Yes How many applies BI Pixie has made to this data agent 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 data agent 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 data agent 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 latest run's correct answers out of all its questions, from 0 to 1. A question that was not scored counts as not answered correctly, so read it with scored and notScored.
scored integer or null No How many of the latest run's questions reached a verdict. Null when the run's counts were not recorded.
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.
passRateChange number or null No The change against the run before, present only when that run asked about the same semantic model.
semanticModelId string or null No The semantic model the latest run asked about.
semanticModelName string or null No
lastRunAtUtc 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/dataAgents/$DATA_AGENT_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

{
  "dataAgentId": "05dd87d1-624f-4ffa-ab88-ee231a75a904",
  "displayName": "Contoso Sales",
  "workspaceId": "e17c1b59-7a2e-491e-acdd-11434854bbb0",
  "workspaceName": "Contoso Sales Analytics",
  "score": 78,
  "previousScore": 74,
  "scoreChange": 4,
  "regimeId": "aa6d9e39-ee9e-46d8-a9d4-089f050ea78e",
  "scoredRounds": 1,
  "findingsCount": 12,
  "publishState": "Published",
  "previewRuntime": true,
  "assessmentCount": 12,
  "lastAssessedAtUtc": "2026-09-14T09:42:17Z",
  "latestAssessmentId": "8c801b5b-a3d8-4166-9dfe-ceb1a3ecf1f4",
  "groundedOn": [
    {
      "itemId": "d972b3f5-a2fa-47ec-94ff-0403a4d159fa",
      "itemType": "SemanticModel",
      "displayName": "Contoso Sales",
      "workspaceId": "e17c1b59-7a2e-491e-acdd-11434854bbb0",
      "assessed": true
    }
  ],
  "optimization": {
    "count": 12,
    "lastAtUtc": "2026-09-14T09:42:17Z",
    "standing": "Applied",
    "lastRevertedAtUtc": "2026-09-14T09:42:17Z"
  },
  "benchmark": {
    "runCount": 12,
    "passRate": 0.75,
    "scored": 12,
    "notScored": 78,
    "passRateChange": 0.05,
    "semanticModelId": "f1fdc461-3ca1-4702-ae48-afc3522409fc",
    "semanticModelName": "Contoso Sales",
    "lastRunAtUtc": "2026-09-14T09:42:17Z"
  },
  "aiProvider": null,
  "links": {
    "assessments": "https://api.bipixie.com/v1/workspaces/e17c1b59-7a2e-491e-acdd-11434854bbb0/dataAgents/05dd87d1-624f-4ffa-ab88-ee231a75a904/aiReadiness/assessments",
    "assess": "https://api.bipixie.com/v1/workspaces/e17c1b59-7a2e-491e-acdd-11434854bbb0/dataAgents/05dd87d1-624f-4ffa-ab88-ee231a75a904/aiReadiness/assess",
    "abTests": "https://api.bipixie.com/v1/workspaces/e17c1b59-7a2e-491e-acdd-11434854bbb0/dataAgents/05dd87d1-624f-4ffa-ab88-ee231a75a904/abTests"
  }
}

List the assessments of a data agent #

GET /v1/workspaces/{workspaceId}/dataAgents/{dataAgentId}/aiReadiness/assessments

Returns the stored assessments of a data agent, newest first. Each one says whether it can be compared with the assessment before it. A data agent 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 data agent
Name In Type Required Description
workspaceId path string (uuid) Yes The id of the Fabric workspace.
dataAgentId path string (uuid) Yes The id of the data agent 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 data agent
Header Description
x-ms-request-id The id of this request. Quote it to support.
The 200 response to List the assessments of a data agent, DataAgentAssessmentList
Field Type Always present Description
value array of DataAgentAssessmentSummary Yes
assessmentId string Yes
assessedAtUtc string or null (date-time) No
score number or null No
findingsCount integer or null No
sourcesCount integer or null No How many items the assessment found the data agent grounded on.
publishState string or null No
regimeId string Yes
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/dataAgents/$DATA_AGENT_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,
      "findingsCount": 12,
      "sourcesCount": 12,
      "publishState": "Published",
      "regimeId": "aa6d9e39-ee9e-46d8-a9d4-089f050ea78e",
      "comparableWithPrevious": true
    }
  ],
  "continuationToken": "eyJza2lwIjoxMDB9",
  "continuationUri": "https://api.bipixie.com/v1/workspaces/e17c1b59-7a2e-491e-acdd-11434854bbb0/dataAgents/05dd87d1-624f-4ffa-ab88-ee231a75a904/aiReadiness/assessments?continuationToken=eyJza2lwIjoxMDB9"
}

Get an assessment of a data agent #

GET /v1/workspaces/{workspaceId}/dataAgents/{dataAgentId}/aiReadiness/assessments/{assessmentId}

Returns one stored assessment of a data agent, whole. The assessment is read from where the account keeps its results, which does not record the permissions it ran with, so usage.access and storage.access say NotRecorded; the document's sources say which were read. An id that is not an assessment of this data agent 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 of a data agent
Name In Type Required Description
workspaceId path string (uuid) Yes The id of the Fabric workspace.
dataAgentId path string (uuid) Yes The id of the data agent 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 of a data agent
Header Description
x-ms-request-id The id of this request. Quote it to support.
The 200 response to Get an assessment of a data agent, DataAgentAssessment
Field Type Always present Description
assessmentId string or null Yes The id of the stored assessment. Null when the assessment was not stored.
dataAgentId string or null Yes
displayName string or null No
workspaceId string or null No
workspaceName string or null No
assessedAtUtc string or null (date-time) No
score number or null Yes The data agent's AI Readiness score, from 0 to 100.
scoreBasic number or null No The score of the deterministic round alone. Equal to score unless an AI round moved it.
scoredRounds integer Yes 1 when only the deterministic round scored; 2 when an AI round did too. One of 1, 2.
findingsCount integer or null No
checksCount integer or null No
publishState string or null No
usage PermissionNote Yes Whether BI Pixie could act on the signed-in person's behalf for one permission: Granted, ConsentRequired when the person has not granted it, or Unavailable when Microsoft did not answer. Known on the result of an operation. An assessment read later from where it is stored does not record the permissions it ran with, and says NotRecorded; its document says which sources were read.
access string Yes One of Granted, ConsentRequired, Unavailable, NotRecorded.
permission string No The permission by name: Dataset.Read.All for usage, Azure Storage user_impersonation for storage, DataAgent.Execute.All for agent. Present with ConsentRequired and Unavailable.
message string No What BI Pixie could not do without the permission, what the result 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: usage, storage or dataAgent.
storage PermissionNote Yes Whether BI Pixie could act on the signed-in person's behalf for one permission: Granted, ConsentRequired when the person has not granted it, or Unavailable when Microsoft did not answer. Known on the result of an operation. An assessment read later from where it is stored does not record the permissions it ran with, and says NotRecorded; its document says which sources were read.
access string Yes One of Granted, ConsentRequired, Unavailable, NotRecorded.
permission string No The permission by name: Dataset.Read.All for usage, Azure Storage user_impersonation for storage, DataAgent.Execute.All for agent. Present with ConsentRequired and Unavailable.
message string No What BI Pixie could not do without the permission, what the result 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: usage, storage or dataAgent.
agent object No Whether BI Pixie could ask a Fabric data agent questions on the signed-in person's behalf, which the AI round needs when the account's AI provider is a data agent. Present only on the result of an operation started with aiChecks; without the permission the round ran and its checks say they could not.
access string Yes One of Granted, ConsentRequired, Unavailable, NotRecorded.
permission string No The permission by name: Dataset.Read.All for usage, Azure Storage user_impersonation for storage, DataAgent.Execute.All for agent. Present with ConsentRequired and Unavailable.
message string No What BI Pixie could not do without the permission, what the result 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: usage, storage or dataAgent.
regime object Yes
id string Yes
stored object Yes
location string Yes One of BIPixie, CustomerOneLake, CustomerStorage, Unknown, None.
reason string or null No
deliveryPending boolean Yes
document object Yes
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/dataAgents/$DATA_AGENT_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",
  "dataAgentId": "05dd87d1-624f-4ffa-ab88-ee231a75a904",
  "displayName": "Contoso Sales",
  "workspaceId": "e17c1b59-7a2e-491e-acdd-11434854bbb0",
  "workspaceName": "Contoso Sales Analytics",
  "assessedAtUtc": "2026-09-14T09:30:05Z",
  "score": 78,
  "scoreBasic": 78,
  "scoredRounds": 1,
  "findingsCount": 12,
  "checksCount": 12,
  "publishState": "Published",
  "usage": {
    "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"
  },
  "storage": {
    "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"
  },
  "agent": {
    "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"
  },
  "stored": {
    "location": "BIPixie",
    "reason": "Not available for this item.",
    "deliveryPending": true
  },
  "document": {
    "schemaVersion": 3
  }
}

Assess a data agent #

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

Starts an assessment of a data agent and answers with the operation to ask about. 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 data agent is a first look; a later assessment makes it a tracked item.

With no body this is the deterministic round. A body of {"aiChecks": true} also asks the account's AI provider the questions the deterministic checks cannot answer, after them, in the same operation; the result then says scoredRounds: 2. When the provider is a Fabric data agent, the round asks it as the signed-in person, which needs a permission they grant; without it the round runs and those checks come back unchecked, as in the portal. An account with no provider is not refused: the checks say why they could not run.

A data agent grounded on a warehouse or a mirrored database can be read fully only with a storage permission the signed-in person grants. Without it the assessment still runs, those sources report unread, and storage.access in the result says ConsentRequired with the page where the permission is granted. The usage permission works the same way, as for a semantic model.

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

Parameters

Parameters for Assess a data agent
Name In Type Required Description
workspaceId path string (uuid) Yes The id of the Fabric workspace.
dataAgentId path string (uuid) Yes The id of the data agent in that workspace.

Request body

JSON, DataAgentAssessRequest. The body is optional.

Request body for Assess a data agent
Field Type Required Description
aiChecks boolean No Also run the round that asks the account's AI provider.

Responses

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

Headers of the 202 response to Assess a data agent
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 data agent, 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 data agent
Header Description
x-ms-request-id The id of this request. Quote it to support.
The 400 response to Assess a data agent, 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/dataAgents/$DATA_AGENT_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/dataAgents/05dd87d1-624f-4ffa-ab88-ee231a75a904/aiReadiness/assess"
}

Preview or write a data agent's optimization #

POST /v1/workspaces/{workspaceId}/dataAgents/{dataAgentId}/aiReadiness/optimize

Offers what the BI Pixie portal's Optimize card offers on a data agent, from its latest assessment: the AI instructions the account's AI provider wrote for it, the published description, and grounding each semantic model source on what that semantic model now holds. A data agent that was never assessed answers 404 AssessmentNotFound.

approval: required answers a preview and writes nothing; its result is a DataAgentOptimizationPreview, kept 24 hours. The body may carry the caller's own instructions, which replace the proposal, and description, which is the only way a description is offered. A later call with the preview's previewId writes it, whole or by keys.

approval: none proposes and writes in one operation, and writes only what a revert can put back: AI instructions and the description. Grounding is rebuilt from the semantic model when it is written, so it has no previous value to restore; it is listed under skipped as NotRestorable and is written only by an apply of a reviewed preview. A proposal with nothing a revert could put back is 400 InvalidRequest before anything is written.

Each change is written, published and assessed again, as in the portal, so each one counts as one of the day's assessments. An apply of several changes writes them one after another: the next starts when a poll of the operation by the person who started it sees the previous one finish, because the write runs as whoever's token starts it. Another member of the account polling reads Running and starts nothing.

Before anything is written, BI Pixie records the previous value and the written value of every change, from the assessment and never from a fresh read, and keeps the record 30 days. If the data agent changed in Fabric since that assessment, the write is refused and the operation fails with ItemChanged. When a later change fails after earlier ones were written, the operation fails and its record keeps what was written, with the rest listed as NotApplied, so revert can still put the written ones back.

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

Parameters

Parameters for Preview or write a data agent's optimization
Name In Type Required Description
workspaceId path string (uuid) Yes The id of the Fabric workspace.
dataAgentId path string (uuid) Yes The id of the data agent in that workspace.

Request body

JSON, one of value, value. The body is required.

Request body for Preview or write a data agent's optimization
Field Type Required Description
approval string No required answers a preview and writes nothing. none proposes and writes what a revert can put back in one operation. Never the default, and audited as such. One of required, none.
instructions string No With approval: AI instructions to propose instead of the ones the account's AI provider wrote.
description string No With approval: the description to propose for the data agent.
previewId string No The preview whose changes are written. From the preview's result.
keys array of string No With previewId: the keys of the preview's changes to write. Left out, every change is written. A key the preview does not have is 400 InvalidRequest.

Responses

202. The preview was made, or the change was started. The body carries the operation's id and address.

Headers of the 202 response to Preview or write a data agent's optimization
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 Preview or write a data agent's optimization, 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 Preview or write a data agent's optimization
Header Description
x-ms-request-id The id of this request. Quote it to support.
The 400 response to Preview or write a data agent's optimization, 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 '{
  "approval": "required"
}' \
  "https://api.bipixie.com/v1/workspaces/$WORKSPACE_ID/dataAgents/$DATA_AGENT_ID/aiReadiness/optimize"

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/dataAgents/05dd87d1-624f-4ffa-ab88-ee231a75a904/aiReadiness/optimize"
}

Put back what a data agent apply changed #

POST /v1/workspaces/{workspaceId}/dataAgents/{dataAgentId}/aiReadiness/revert

Writes back the previous AI instructions and description an apply to this data agent replaced, and nothing else. Grounding the apply aligned is listed under skipped as NotRestorable, because it has no previous value; an apply that aligned only grounding is 400 InvalidRequest. The revert counts as one of the day's assessments for each change it writes, like the apply, and its result is the same record shape with reverts naming the apply it put back.

It is refused before anything is written when a later apply made through this API still stands on one of the same changes (409 ItemChanged), for an apply that has not finished (409 OperationInProgress), wrote nothing, or was already reverted (400 InvalidRequest), and for an id that is not an apply of this data agent by this account (404 OperationNotFound). If the data agent changed in Fabric since the apply, the write is refused and the operation fails with ItemChanged.

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

Parameters

Parameters for Put back what a data agent apply changed
Name In Type Required Description
workspaceId path string (uuid) Yes The id of the Fabric workspace.
dataAgentId path string (uuid) Yes The id of the data agent in that workspace.

Request body

JSON, object. The body is required.

Request body for Put back what a data agent apply changed
Field Type Required Description
operationId string Yes The id the apply answered, also its result's revertOperationId.

Responses

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

Headers of the 202 response to Put back what a data agent apply changed
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 Put back what a data agent apply changed, 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 Put back what a data agent apply changed
Header Description
x-ms-request-id The id of this request. Quote it to support.
The 400 response to Put back what a data agent apply changed, 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 '{
  "operationId": "<string>"
}' \
  "https://api.bipixie.com/v1/workspaces/$WORKSPACE_ID/dataAgents/$DATA_AGENT_ID/aiReadiness/revert"

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/dataAgents/05dd87d1-624f-4ffa-ab88-ee231a75a904/aiReadiness/revert"
}

What's next