Work with the BI Pixie API

The BI Pixie API follows the conventions of the Microsoft Fabric REST API, so a client written for Fabric needs no new habits.

Follow a long-running operation

A call that starts work answers 202 Accepted with three headers, Location, x-ms-operation-id and Retry-After, and a body that repeats the operation's id and address for a client that shows no headers. Ask for the operation's state until its status is Succeeded, Failed or Cancelled, then ask for its result. Operations are kept for 7 days.

Read a list page by page

A list answers value, and continuationToken with continuationUri when there is another page. Both are absent on the last page.

Errors

Every refusal is an ErrorResponse. errorCode is the stable contract. message is written for people and can change. requestId is also sent as the x-ms-request-id header.

Fields of an ErrorResponse
Field	Type	Always present	Description
`errorCode`	string	Yes	Which refusal this is: one of the error codes below.
`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

Error codes

Each code keeps its meaning once published. New codes can be added over time, and a code is never reused.

Every error code, with the HTTP status it is answered with
HTTP	Code	Means
400	`InvalidRequest`	The request is not well formed: a body, a field or a parameter is missing or is not what the route takes. The message names it.
400	`InvalidPreview`	The preview named is not available: it is past its 24 hours, was made for another item or another kind of change, or was already applied and that apply still stands.
400	`PayloadTooLarge`	The body is larger than the route accepts.
400	`BenchmarkQuestionsMissing`	A benchmark run was asked for with no saved questions to ask.
400	`OperationNotSupportedForItem`	The item is not one this call applies to, such as a schedule BI Pixie maintains itself.
401	`Unauthorized`	No token was sent, or the token could not be read or verified.
401	`TokenExpired`	The token has expired. Get a new one and send the call again.
401	`InsufficientScopes`	The token does not carry the scope the route needs: a call that starts work needs `BIPixie.ReadWrite.All`.
401	`AppOnlyTokenNotSupported`	The token belongs to an application, not to a person. The API acts as a signed-in person only.
403	`UserNotRegistered`	The signed-in person is not a user of any BI Pixie account. Signing in to the portal once registers them.
403	`AccountNotActive`	The account is suspended, deactivated or not yet active, so it can start no work.
403	`AdminRoleRequired`	The call is for an account admin, and the signed-in person is a member.
403	`FeatureNotInPlan`	The plan does not include what was asked for. The message names it.
403	`FeatureTurnedOff`	An administrator of the account turned off the feature this call reaches. Two features answer this: with Add Pixies off, every call that adds Pixies answers it, while removing Pixies still works; with AI features off, every AI Readiness, benchmark, A/B test and data agent route answers it. Either stays this way until an administrator turns the feature on in Account settings.
403	`LicenseNotYours`	The license named is not one the signed-in person may act under.
403	`TrackedItemLimitReached`	The account has used every tracked item its plan includes, and this call would claim one.
403	`LicenseTrackedItemLimitReached`	The license has used every tracked item it may hold, and this call would claim one.
403	`FabricConsentRequired`	The signed-in person has not granted BI Pixie the Fabric permission the call needs. The `consentUrl` parameter is the portal page where they grant it.
403	`FabricAccessDenied`	The signed-in person's Power BI account does not have access to the workspace or the item, or Fabric refused to list their workspaces when BI Pixie set up the account's processing region. The `reason` parameter says which when it is not the item.
404	`WorkspaceNotFound`	No workspace with this id is visible to the signed-in person.
404	`ItemNotFound`	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.
404	`AssessmentNotFound`	The account holds no assessment by this id for this item, or none at all when the call needs the latest one.
404	`RunNotFound`	The account holds no benchmark run by this id.
404	`AbTestNotFound`	The account holds no A/B test by this id. It may have been deleted.
404	`OperationNotFound`	No operation by this id was started by this account in the last 7 days, or the id is not an apply of this item when a revert names one.
404	`ScheduleNotFound`	The license holds no schedule by this id.
404	`AiProviderNotFound`	The account has no saved AI by this id. It may have been removed, or replaced when another AI was made the one BI Pixie writes with.
404	`AiCredentialNotFound`	The account has no saved credential by this id. It is removed once no saved AI uses it.
409	`OperationInProgress`	Work on this item is already running, or the operation asked about has not finished. The message names the operation, and `Retry-After` says when to ask again.
409	`OperationHasNoResult`	The operation failed or was cancelled, so it has no result. Its state carries the reason.
409	`ResultNotReady`	The A/B run has not finished, so its comparison is not available yet. Reading the run says where it is, and the call can be sent again after `Retry-After`.
409	`ScheduleConflict`	The item is already on another schedule of the license, or the schedule belongs to another license. The message names the schedule.
409	`AiProviderConflict`	The change does not fit the account's saved AIs as they stand, and nothing was saved. The `reason` parameter says why: `AlreadySaved`, `ListFull`, `NotTheWriter`, `IsTheWriter`, or `ChangedMeanwhile`, when another change landed at the same moment and the call can be sent again.
409	`ItemChanged`	The item changed since the preview was made, or a later apply stands on it, so nothing was written. The message names what changed.
409	`CapacityPaused`	The Fabric capacity behind the item is paused, so it could not be read. `Retry-After` says when to try again, once a capacity admin resumes it.
410	`OperationExpired`	The operation is older than 7 days and its state is no longer kept. The record it created, if any, is still addressable.
412	`RegionNotReady`	The account's processing region is still being set up after the call waited for it. BI Pixie sets a region up on the first call that starts work, and that call usually carries on without this answer. `Retry-After` says when to try again.
412	`CapacityRequired`	The call needs a Fabric capacity behind the workspace, and there is none.
412	`CapacityUnpaid`	The workspace's capacity is a trial or an unpaid one, which Fabric does not allow for this call.
412	`StoreNotConnected`	The account keeps its results in its own storage, and that storage has to be reconnected by an account admin in the portal.
429	`RequestBlocked`	The signed-in person, or the account, has sent more requests in this window than the limit allows. `Retry-After` says when the window opens.
429	`AssessmentDailyLimitReached`	The account has used every assessment its plan includes today. `Retry-After` says when the next day begins, at midnight UTC.
429	`BenchmarkRunsExhausted`	The account has used every benchmark run its plan includes.
429	`OptimizationApplyDailyLimitReached`	The account has used every optimization apply its plan includes today. A revert counts as one. `Retry-After` says when the next day begins, at midnight UTC.
429	`FirstLookLimitReached`	The account has used every first look its plan includes, so an item not yet tracked cannot be assessed.
429	`BenchmarkBuildLimitReached`	The account has generated benchmark questions as many times today as the daily limit allows. `Retry-After` says when the next day begins, at midnight UTC.
502	`FabricUnavailable`	Microsoft did not answer as expected. The call can be sent again.
502	`StoreUnavailable`	The storage the account keeps its results in, or BI Pixie's own record of a preview or an apply, could not be read or written. The call can be sent again in a moment.
503	`ThrottleStoreUnavailable`	BI Pixie could not check the request allowance, so the call was not started. The call can be sent again after `Retry-After`.
500	`UnknownError`	Something BI Pixie did not expect. The `requestId` identifies it to support.

Why an accepted operation failed

Why an operation that was accepted then failed. Each code keeps its meaning once published. New codes can be added over time, and a code is never reused.

Every operation error code, with what happened and what to do next
Code	Means
`AssessmentTimedOut`	The assessment has not finished in the time BI Pixie waits for one. The code is worked out each time the operation is read and is never stored, so when the assessment finishes later, its outcome replaces this code on the next read. You can ask about the operation again later, or start the assessment again.
`CapacityPaused`	The Fabric capacity behind the item was paused when BI Pixie came to read it, so the work was not done. Once a capacity admin resumes the capacity, you can start the work again.
`FabricAccessDenied`	The signed-in person's Power BI account did not have access to the item when BI Pixie came to read it, so the work was not done. Once that access is granted in Fabric, you can start the work again.
`ItemNotFound`	The item could not be found in Fabric when BI Pixie came to read it. It may have been deleted since the work was started, or the signed-in person may no longer be able to see it.
`FabricUnavailable`	Fabric did not answer as expected while BI Pixie worked on the item. You can start the work again.
`CapacityBusy`	The Fabric capacity behind the item was over its limit when BI Pixie came to read it, so the work was not done. Fabric clears this on its own once the capacity's load falls, so you can start the work again a few minutes later. Starting it again at once usually meets the same limit. A preview that failed this way changed nothing.
`ItemNotReadable`	BI Pixie could not read the item's definition. For an assessment, none of the semantic model's tables could be read, or the data agent's definition could not be read, so there was nothing to assess. For an optimization, the semantic model's existing AI instructions could not be read, so nothing was changed. A semantic model can be assessed only when its definition is in TMDL format with readable table files.
`ItemChanged`	The item changed in Fabric after the preview was made, or a later apply stands on it, so nothing was written. You can make a new preview and apply it.
`TrackedItemLimitReached`	In a run over many semantic models, this semantic model was not assessed, because assessing it would make it a tracked item and the account has no tracked items left. The other semantic models in the run are not affected.
`FirstLookLimitReached`	In a run over many semantic models, this semantic model was not assessed, because it is not yet tracked and the account has used every first look its plan includes. The other semantic models in the run are not affected.
`AssessmentNotStarted`	In a run over many semantic models, BI Pixie could not queue this semantic model for assessment. It was not assessed, and it does not count against the account's assessments for the day. You can start the assessment again.
`AssessmentFailed`	The assessment failed for a reason that no more specific code describes. You can start the assessment again. If it fails again, you can quote the operation id to support.
`OptimizationFailed`	A preview, an apply or a revert failed for a reason that no more specific code describes. You can make a new preview and apply it again. If it fails again, you can quote the operation id to support.
`QuestionsNotGenerated`	BI Pixie could not write benchmark questions for the semantic model. You can ask for the questions again. If it fails again, you can quote the operation id to support.
`BenchmarkRunFailed`	A benchmark run, or one side of an A/B test run, failed for a reason that no more specific code describes. You can run the benchmark again. If it fails again, you can quote the operation id to support.
`AddPixiesFailed`	Pixies could not be added to a report. The code is on that report's outcome in the result, and it is the operation's own error when no report succeeded. You can add Pixies to that report again. If it fails again, you can quote the operation id to support.
`RemovePixiesFailed`	The Pixies could not be removed from a report. The code is on that report's outcome in the result, and it is the operation's own error when no report succeeded. You can remove the Pixies from that report again. If it fails again, you can quote the operation id to support.
`SideBNotStarted`	Side A of an A/B test run finished, but side B never started. In a run started through the API, side B starts when the person who started the run asks about the operation, and nobody asked in the week after the run started, so BI Pixie failed the run. You can run the test again, and ask about the operation until it finishes.

Throttling

Requests are counted for each signed-in person over a fixed window of 60 seconds that refills all at once. Over the limit, the answer is 429 with errorCode RequestBlocked and a Retry-After header.

For the numbers, see Limits and allowances.