Job Scheduler - Run On Demand Item Job

Service:: Core

API Version:: v1

Run on-demand item job instance.

Note

The URL for this API has been updated to include the job type as part of the path, replacing the previous use of a query parameter. For backward compatibility, invocations using the query parameter are still supported.

Required Delegated Scopes

For item APIs use these scope types:

Generic scope: Item.Execute.All
Specific scope: itemType.Execute.All (for example: Notebook.Execute.All)

for more information about scopes, see: scopes article.

Microsoft Entra supported identities

This API supports the Microsoft identities listed in this section.

Identity	Support
User	Yes
Service principal and Managed identities	Yes

Interface

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{itemId}/jobs/{jobType}/instances

URI Parameters

Name	In	Required	Type	Description
itemId	path	True	string (uuid)	The item ID.
jobType	path	True	string	Job type
workspaceId	path	True	string (uuid)	The workspace ID.

Request Body

Name	Type	Description
executionData	object	The execution data for an on-demand job. This is fixed static data, defined by the specific item job type.
parameters	Parameter[]	The parameter list for an on-demand job. These are per-run, user-defined inputs that tailor this invocation. Note: This property is not broadly supported. If the API returns an error with errorCode `FeatureNotAvailable` and errorMessage `Parameter is not allowed for this item type or this item job type`, the `parameters` property is not supported for the specified item type or item job type.

Responses

Name Type Description

202 Accepted

Name	Type	Description
202 Accepted		Request accepted, job execution is in progress. Headers Location: string Retry-After: integer
429 Too Many Requests	ErrorResponse	The service rate limit was exceeded. The server returns a `Retry-After` header indicating, in seconds, how long the client must wait before sending additional requests. Headers Retry-After: integer
Other Status Codes	ErrorResponse	Common error codes: InsufficientPrivileges - The caller does not have sufficient permissions to run job instance. InvalidJobType - The requested job type is invalid. TooManyRequestsForJobs - The caller requests too many on-demand job requests. ItemNotFound - Requested item ID not found.

Request accepted, job execution is in progress.

Headers

Location: string
Retry-After: integer

429 Too Many Requests

ErrorResponse

The service rate limit was exceeded. The server returns a Retry-After header indicating, in seconds, how long the client must wait before sending additional requests.

Headers

Retry-After: integer

Other Status Codes

ErrorResponse

Common error codes:

InsufficientPrivileges - The caller does not have sufficient permissions to run job instance.
InvalidJobType - The requested job type is invalid.
TooManyRequestsForJobs - The caller requests too many on-demand job requests.
ItemNotFound - Requested item ID not found.

Examples

Run item job instance with no request body example

Run item job instance with request body containing both executionData and parameters example

Run item job instance with request body containing executionData example

Run item job instance with request body containing parameters example

Run item job instance with no request body example

Sample request

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/4b218778-e7a5-4d73-8187-f10824047715/items/431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7/jobs/DefaultJob/instances

Sample response

Status code:: 202

Location: https://api.fabric.microsoft.com/v1/workspaces/4b218778-e7a5-4d73-8187-f10824047715/items/431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b
Retry-After: 60

Run item job instance with request body containing both executionData and parameters example

Sample request

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/items/dddddddd-9999-0000-1111-eeeeeeeeeeee/jobs/Execute/instances

{
  "executionData": {
    "executeOption": "ApplyChangesIfNeeded"
  },
  "parameters": [
    {
      "name": "Threshold",
      "value": "start",
      "type": "Automatic"
    },
    {
      "name": "OrderKey",
      "value": 25,
      "type": "Automatic"
    }
  ]
}

Sample response

Status code:: 202

Location: https://api.fabric.microsoft.com/v1/workspaces/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/items/dddddddd-9999-0000-1111-eeeeeeeeeeee/jobs/instances?jobType=Execute
Retry-After: 60

Run item job instance with request body containing executionData example

Sample request

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/4b218778-e7a5-4d73-8187-f10824047715/items/431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7/jobs/DefaultJob/instances

{
  "executionData": {
    "tableName": "Table1",
    "optimizeSettings": {
      "vOrder": true
    }
  }
}

Sample response

Status code:: 202

Location: https://api.fabric.microsoft.com/v1/workspaces/4b218778-e7a5-4d73-8187-f10824047715/items/431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b
Retry-After: 60

Run item job instance with request body containing parameters example

Sample request

HTTP

POST https://api.fabric.microsoft.com/v1/workspaces/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/items/dddddddd-9999-0000-1111-eeeeeeeeeeee/jobs/Execute/instances

{
  "parameters": [
    {
      "name": "param1",
      "value": "value1",
      "type": "Text"
    },
    {
      "name": "param2",
      "value": true,
      "type": "Boolean"
    },
    {
      "name": "param3",
      "value": 123,
      "type": "Number"
    }
  ]
}

Sample response

Status code:: 202

Location: https://api.fabric.microsoft.com/v1/workspaces/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/items/dddddddd-9999-0000-1111-eeeeeeeeeeee/jobs/instances?jobType=Execute
Retry-After: 60

Definitions

Name	Description
ErrorRelatedResource	The error related resource details object.
ErrorResponse	The error response.
ErrorResponseDetails	The error response details.
ItemJobParameterType	A string that represents the parameter's type. Additional types may be added over time.
Parameter	An item job parameter.
RunOnDemandItemJobRequest	Run on demand item job instance payload

ErrorRelatedResource

Object

The error related resource details object.

Name	Type	Description
resourceId	string	The resource ID that's involved in the error.
resourceType	string	The type of the resource that's involved in the error.

ErrorResponse

Object

The error response.

Name	Type	Description
errorCode	string	A specific identifier that provides information about an error condition, allowing for standardized communication between our service and its users.
message	string	A human readable representation of the error.
moreDetails	ErrorResponseDetails[]	List of additional error details.
relatedResource	ErrorRelatedResource	The error related resource details.
requestId	string (uuid)	ID of the request associated with the error.

ErrorResponseDetails

Object

The error response details.

Name	Type	Description
errorCode	string	A specific identifier that provides information about an error condition, allowing for standardized communication between our service and its users.
message	string	A human readable representation of the error.
relatedResource	ErrorRelatedResource	The error related resource details.

ItemJobParameterType

Enumeration

A string that represents the parameter's type. Additional types may be added over time.

Value	Description
VariableReference	The type of parameter is a variable reference.
Integer	The type of parameter is an integer.
Number	The type of parameter is a number, it accepts both integer and float values.
Text	The type of parameter is a text.
Boolean	The type of parameter is a boolean.
DateTime	The type of parameter is a datetime in UTC, using the YYYY-MM-DDTHH:mm:ssZ format.
Guid	The parameter type is a string representation of a GUID, using 00000000-0000-0000-0000-000000000000 format. See https://learn.microsoft.com/dotnet/api/system.guid.tostring for formatting details, and please use the default format: "D".
Automatic	The parameter type is automatically determined. Note: this type may not be supported for all item job types.

Parameter

Object

An item job parameter.

Name	Type	Description
name	string	The parameter name, specified by the caller, must be unique (case-insensitive check) and no longer than 256 characters.
type	ItemJobParameterType	The parameter type.
value	object	The parameter value based on the parameter type.

RunOnDemandItemJobRequest

Object

Run on demand item job instance payload

Name	Type	Description
executionData	object	The execution data for an on-demand job. This is fixed static data, defined by the specific item job type.
parameters	Parameter[]	The parameter list for an on-demand job. These are per-run, user-defined inputs that tailor this invocation. Note: This property is not broadly supported. If the API returns an error with errorCode `FeatureNotAvailable` and errorMessage `Parameter is not allowed for this item type or this item job type`, the `parameters` property is not supported for the specified item type or item job type.

Share via

Job Scheduler - Run On Demand Item Job

Required Delegated Scopes

Microsoft Entra supported identities

Interface

URI Parameters

Request Body

Responses

Examples

Run item job instance with no request body example

Sample request

Sample response

Run item job instance with request body containing both executionData and parameters example

Sample request

Sample response

Run item job instance with request body containing executionData example

Sample request

Sample response

Run item job instance with request body containing parameters example

Sample request

Sample response

Definitions

ErrorRelatedResource

ErrorResponse

ErrorResponseDetails

ItemJobParameterType

Parameter

RunOnDemandItemJobRequest