Skip to content

Optimizations

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

Preview an optimization of a semantic model #

POST /v1/workspaces/{workspaceId}/semanticModels/{semanticModelId}/aiReadiness/{kind}/preview

Proposes changes of one kind to a semantic model and writes nothing. The request has no body. The answer is the operation to ask about; its result is the preview, kept for 24 hours under its previewId, which apply takes so that exactly the previewed changes are written and nothing else.

The preview is the one the BI Pixie portal's card makes, with the account's AI provider. Each change names one object, its current value and the proposed value, under a key. For aiInstructions there is one object, the semantic model's AI instructions, so there is one change or none, and skipped says why none. For descriptions the objects are the measures, columns and tables the semantic model's latest assessment found a description could fix, capped as the portal caps them, each keyed table|object (the table's own description is keyed table|); a semantic model with no assessment in this account answers 404 AssessmentNotFound.

A kind with nothing to propose is not an error. Every kind answers 202 with an operation whose preview holds no changes and says why in nothingToDo, including the two that can tell in advance from the latest assessment. Those two spend nothing to say it: no semantic model is downloaded and the account's AI provider is never called. Until 2026-10-06 descriptions and properties answered 400 InvalidRequest here while the other two kinds answered an empty preview, so the same situation reached a caller two different ways.

For properties the objects are the measures the latest assessment found outside any display folder and the text columns it found summarized by default, each keyed table|object; the preview is the two the portal's cards make, run as one operation, and each change says which property it writes. A display folder is proposed first from the measures' names, as the portal proposes it, and by the account's AI provider for the measures that reading left unplaced; a field default is always none. existingFolders lists the folders each table already has, so a proposal into one of them can be told from a new folder. The same two refusals apply as for descriptions.

Two optional permissions ride with the request: reading usage on the signed-in person's behalf, which weights the proposal by how the semantic model is used, and asking a Fabric data agent questions, which the AI provider needs when it is itself a data agent. Without usage, the preview runs and usageInProposal is false, and usage says ConsentRequired, names the permission and says why in message. Without the data agent permission, an account whose AI provider is a Fabric data agent gets no proposals from it: the objects it would have answered for are skipped as PermissionRequired rather than NothingProposed, reason is PermissionRequired, message names the permission, and agent.consentUrl is the page where it is granted. A preview that skips objects as PermissionRequired is not a finding that the semantic model needs nothing.

The kinds arrive one at a time; kind names the ones built, and apply says when it is not yet built for one of them.

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

Parameters

Parameters for Preview an optimization 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.
kind path string Yes Which kind of optimization. The four kinds of a semantic model arrive one at a time, and this lists the ones built; a kind not listed answers 400 InvalidRequest naming the ones that are. aiInstructions, descriptions and properties each have their preview, apply, unattended apply and revert. aiDataSchema has its preview, its apply and its revert; its unattended apply answers 400 InvalidRequest, because which fields an AI leaves out is a choice for a person to review. One of aiInstructions, descriptions, properties, aiDataSchema.

Responses

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

Headers of the 202 response to Preview an optimization of 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 Preview an optimization of 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 Preview an optimization of a semantic model
Header Description
x-ms-request-id The id of this request. Quote it to support.
The 400 response to Preview an optimization of 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/$KIND/preview"

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/4205c3c5-9923-4a64-98fe-0aebafaf5e7a/preview"
}

Apply a previewed optimization to a semantic model #

POST /v1/workspaces/{workspaceId}/semanticModels/{semanticModelId}/aiReadiness/{kind}/apply

Writes exactly the changes of a preview, or the subset named by keys, to the semantic model, through the same write the BI Pixie portal's card makes. The answer is the operation to ask about; its result is what was written and what it replaced, object by object, under the id a revert takes.

The preview is named by previewId. One older than 24 hours, or made for another item or another kind, answers 400 InvalidPreview and writes nothing. approval has no default: a body naming neither previewId nor approval is 400 InvalidRequest.

For descriptions, each change is one table, column or measure. An object the semantic model no longer holds as the preview recorded it is not written: it is listed under skipped with the reason and left out of applied, so the record says only what landed. A description that changed since the preview refuses the whole apply, and the operation fails with ItemChanged.

For properties, the apply is the portal's two property applies in turn, display folders then field defaults, each counting as one of the day's optimization applies, under one record. The second starts on the poll that first sees the first land, and only when that poll is the person who started the operation, as the unattended apply does; allowanceImpact on that poll says what is left. A flow that fails after an earlier one wrote leaves those writes: the operation succeeds in part, and the keys that did not land are listed under skipped with the failure's error code as the reason, so revert puts back exactly what landed. A measure the fresh semantic model holds in another folder than the preview saw, or a column no longer there, is skipped with the portal's own reason.

approval: none is the unattended apply: one operation that proposes and writes, with no preview to review. For descriptions the proposal is made from the latest assessment's writable findings, as the preview is, and for properties from its display folder and field default findings through the two previews, so a semantic model never assessed is 404 AssessmentNotFound; the properties write is then the two writes in turn, as the attended apply. It is never the default and is audited as such. The proposal is made first, as a preview is; the write starts on the poll that first sees the proposal land, and only when that poll is the person who started the operation, because the write runs as whoever's token starts it. Another member of the account polling reads Running and starts nothing. A proposal with nothing to write ends the operation as succeeded, with applied empty and skipped saying why. The result carries every previous value, and revert undoes it.

Before anything is written, BI Pixie records the previous value and the written value of every object the apply changes, from the preview and never from a fresh read, so what was shown is what a revert restores. The record is kept 30 days.

The apply counts toward the day's optimization applies and holds the semantic model's write lock while it runs: a second change to the same semantic model is 409 OperationInProgress until the first ends. If what the preview showed changed in the semantic model since the preview was made, the job refuses to write over it and the operation fails with ItemChanged: nothing was written, and a new preview is the remedy.

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

Parameters

Parameters for Apply a previewed optimization to 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.
kind path string Yes Which kind of optimization. The four kinds of a semantic model arrive one at a time, and this lists the ones built; a kind not listed answers 400 InvalidRequest naming the ones that are. aiInstructions, descriptions and properties each have their preview, apply, unattended apply and revert. aiDataSchema has its preview, its apply and its revert; its unattended apply answers 400 InvalidRequest, because which fields an AI leaves out is a choice for a person to review. One of aiInstructions, descriptions, properties, aiDataSchema.

Request body

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

Request body for Apply a previewed optimization to a semantic model
Field Type Required Description
previewId string No The preview whose changes are written. From the preview's result.
keys array of string No The keys of the preview's changes to write. A key the preview does not have is 400 InvalidRequest. Left out, every change is written, with one exception: for aiDataSchema, whose preview proposes more than it recommends, only the changes BI Pixie recommends are written (recommendedKeys, and recommended on each change). When that kind recommends none of them, an apply that leaves out keys is refused with 400 InvalidRequest, so nothing is written that BI Pixie did not advise; name the changes you chose to write them.
approval string No none proposes and writes in one operation, without a preview. Never the default, and audited as such. One of none.
values object No Your own wording for some of the preview's changes, a change key to the text to write in place of what the preview proposed. Sent only with previewId, for aiInstructions, description and displayFolder changes. The text may not be blank; AI instructions keep to the length the preview allows. A description may break lines with CRLF, LF or CR, and each line is written as its own /// line in the file's own line ending; any other line-break character (U+2028, U+2029, a vertical tab, a form feed) is refused. A display folder is one line with no tab and at most 100 characters. A key the apply does not write, a summarizeBy or aiDataSchema change, or values beside approval is 400 InvalidRequest, and nothing is written.

Responses

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

Headers of the 202 response to Apply a previewed optimization to 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 Apply a previewed optimization to 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 Apply a previewed optimization to a semantic model
Header Description
x-ms-request-id The id of this request. Quote it to support.
The 400 response to Apply a previewed optimization to 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" \
  -H "Content-Type: application/json" \
  -d '{
  "previewId": "01a0ee7c-7037-7fd1-8f82-3c2501ef86c4"
}' \
  "https://api.bipixie.com/v1/workspaces/$WORKSPACE_ID/semanticModels/$SEMANTIC_MODEL_ID/aiReadiness/$KIND/apply"

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/4205c3c5-9923-4a64-98fe-0aebafaf5e7a/apply"
}

Put back what an apply changed #

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

Restores the previous value of every object an apply changed, and nothing else. The apply is named by the operationId it answered; its record, kept 30 days, holds what it wrote and what it replaced, and the revert writes the latter back through the same write the apply made. AI instructions that were empty before the apply are put back as empty. For descriptions, a description that was empty before the apply is removed again, each object is addressed as the apply reviewed it, and an object the semantic model no longer holds that way is listed under skipped.

For properties, the revert is the same two writes in turn as the apply, display folders then field defaults, each counting as one of the day's optimization applies. A measure or column is put back only while it still holds what the apply wrote: one already back, one changed since, or one no longer there is listed under skipped with the reason, never a refusal of the whole revert. A folder the measure did not have before is removed, a default the column carried before is put back, and a column that carried none is left to Power BI's own default again. When a later write fails after an earlier one put objects back, the operation succeeds in part, skipped names what did not go back with the failure's error code, and the apply's record stays Applied, since some of what it wrote still stands; a second revert of it puts back what is left.

A revert is an apply for the day's optimization applies and for the semantic model's write lock, so a loop cannot write for free. It is not an optimization: the semantic model's optimization.count and lastAtUtc stay as the apply left them, because putting a change back is not a change toward readiness. Its operation's result is the same record shape, with reverts naming the apply it put back; the apply's own record then says Reverted and by which operation.

It is refused before anything is written when a later apply made through this API still stands on one of the same objects, 409 ItemChanged naming that object and that apply; reverting that apply first puts this one back within reach. It is also refused 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 semantic model by this account (404 OperationNotFound). If the semantic model changed since the apply outside this API, the job refuses to write over it 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 an apply changed
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.

Request body

JSON, object. The body is required.

Request body for Put back what an 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 an 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 an 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 an apply changed
Header Description
x-ms-request-id The id of this request. Quote it to support.
The 400 response to Put back what an 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/semanticModels/$SEMANTIC_MODEL_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/semanticModels/f1fdc461-3ca1-4702-ae48-afc3522409fc/aiReadiness/revert"
}

Optimize a semantic model, every kind at once #

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

Every kind of optimization of a semantic model in one operation. kinds names the kinds, in any order, and defaults to all four; they run in the order aiInstructions, descriptions, properties, aiDataSchema, which is the order the writes run. approval has no default: required makes the previews and stops for review, none writes what they propose as well.

The bundle is an operation of operations. Each kind runs as the operation its own route starts, recorded as a child with its own operation id, so every child's result, record and revert are exactly what that route gives. The previews start at once. A kind with nothing to propose from is listed as Skipped with that kind's own reason rather than refusing the bundle; when every kind refuses, the bundle answers as the first kind's route did, and nothing is started. The result of approval: required is the bundle preview, kept 24 hours under its previewId, which optimize/apply takes; it lists each kind's operation, its standing and its own previewId, and succeeds when any kind's preview did.

With approval: none the applies follow, one kind at a time, since a semantic model takes one apply at a time: each child apply starts on the poll that first sees the previous child end, when that poll is the person who started the bundle, with that poll's own token. A kind whose own route refuses approval: none (aiDataSchema) is previewed and not written, listed as skipped with that route's own words, so its preview is there to apply by hand. A child that fails or is refused does not stop the next kind; the bundle succeeds when any child applied and is listed under each kind, and every child that applied has its own revertOperationId.

When the caller stops polling, the bundle stands still: the running child ends on its own and nothing after it starts, because a write runs only as the person whose token is in the poll. The owner's next poll, after any gap, moves the bundle one step, as long as the previews are within their 24 hours and the operation within its 7 days; when the next child can no longer start, that poll declares the bundle finished in part. Another member's poll reads Running and starts nothing. Each child apply counts toward the day's optimization applies as its kind does.

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

Parameters

Parameters for Optimize a semantic model, every kind at once
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.

Request body

JSON, OptimizationBundleRequest. The body is required.

Request body for Optimize a semantic model, every kind at once
Field Type Required Description
kinds array of string No The kinds to optimize, in any order. Left out, every kind. A kind named twice, or unknown, is 400 InvalidRequest.
approval string Yes required makes the previews and stops for review; none writes what they propose as well, and is audited as such. One of required, none.

Responses

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

Headers of the 202 response to Optimize a semantic model, every kind at once
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 Optimize a semantic model, every kind at once, 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 Optimize a semantic model, every kind at once
Header Description
x-ms-request-id The id of this request. Quote it to support.
The 400 response to Optimize a semantic model, every kind at once, 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 '{
  "kinds": [
    "aiInstructions",
    "descriptions",
    "properties",
    "aiDataSchema"
  ],
  "approval": "required"
}' \
  "https://api.bipixie.com/v1/workspaces/$WORKSPACE_ID/semanticModels/$SEMANTIC_MODEL_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/semanticModels/f1fdc461-3ca1-4702-ae48-afc3522409fc/aiReadiness/optimize"
}

Write a reviewed bundle preview #

POST /v1/workspaces/{workspaceId}/semanticModels/{semanticModelId}/aiReadiness/optimize/apply

Writes the kinds a bundle preview proposed, or the named subset, one kind's apply at a time, each as that kind's own apply with the child preview the bundle kept, in the order the writes run. The first child starts with this request; each next one starts on the poll that first sees the previous child end, when that poll is the person who started the bundle. A child refused or failed does not stop the next kind. The result lists each kind's operation, its standing and its own revertOperationId; the bundle's operation id is what optimize/revert takes.

A bundle preview older than 24 hours or made for another semantic model is 400 InvalidPreview; one already applied is 400 InvalidPreview naming the apply; a kind not in the preview is 400 InvalidRequest.

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

Parameters

Parameters for Write a reviewed bundle preview
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.

Request body

JSON, OptimizationBundleApplyRequest. The body is required.

Request body for Write a reviewed bundle preview
Field Type Required Description
previewId string Yes The bundle preview's id, from the bundle operation's result.
kinds array of string No The kinds of the preview to write. Left out, every kind it has.

Responses

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

Headers of the 202 response to Write a reviewed bundle preview
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 Write a reviewed bundle preview, 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 Write a reviewed bundle preview
Header Description
x-ms-request-id The id of this request. Quote it to support.
The 400 response to Write a reviewed bundle preview, 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 '{
  "previewId": "01a0ee7c-7037-7fd1-8f82-3c2501ef86c4"
}' \
  "https://api.bipixie.com/v1/workspaces/$WORKSPACE_ID/semanticModels/$SEMANTIC_MODEL_ID/aiReadiness/optimize/apply"

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/optimize/apply"
}

Put back what a bundle apply changed #

POST /v1/workspaces/{workspaceId}/semanticModels/{semanticModelId}/aiReadiness/optimize/revert

Puts back every kind a bundle apply wrote, one kind's revert at a time, in the reverse of the order the writes ran, each as that kind's own revert of the child apply. The first child starts with this request; each next one on the owner's poll that first sees the previous child end. A child refused or failed does not stop the next kind. The bundle apply's record says Reverted only when every kind went back; a child's own revertOperationId still takes a revert on its own.

Refused for an id that is not a bundle apply of this semantic model by this account (404 OperationNotFound), one not finished (409 OperationInProgress), one that wrote nothing, or one already reverted (400 InvalidRequest).

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

Parameters

Parameters for Put back what a bundle apply changed
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.

Request body

JSON, object. The body is required.

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

Responses

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

Headers of the 202 response to Put back what a bundle 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 bundle 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 bundle 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 bundle 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": "01a0ee7c-7037-7fd1-8f82-3c2501ef86c4"
}' \
  "https://api.bipixie.com/v1/workspaces/$WORKSPACE_ID/semanticModels/$SEMANTIC_MODEL_ID/aiReadiness/optimize/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/semanticModels/f1fdc461-3ca1-4702-ae48-afc3522409fc/aiReadiness/optimize/revert"
}

What's next