Create and Update Single Schedules

Create and update PBRS single schedules for Power BI Service reports, Power BI Paginated Reports, SQL Server Reporting Services (SSRS), and Power BI Report Server (PBIRS).

A schedule combines a reporting source, recurrence, output settings, and delivery destinations. Creating the schedule does not establish that its report can render or that delivery will succeed. Retrieve the saved configuration and run a controlled test before enabling recurring execution.

Before you begin

You need:

• A running PBRS REST API service.
• A valid access token and the required permissions.
• An existing PBRS destination folder.
• A configured reporting account with access to the selected report.
• The report URL or reporting-server path.
• A controlled delivery destination.

Use Discover Folders, Reports, and Reporting Resources to obtain the required identifiers.

The examples create ordinary single schedules with DataDriven set to false. Use Create Packages and Data-Driven Schedules for data-driven workflows.

Choose the correct operation

All paths below begin with /api/SingleSchedule/.

Use the operation and request model for the selected report source. SSRS and PBIRS schedules do not use the same account fields as Power BI Service schedules.

Understand the schedule definition

Use JSON for these examples. It preserves nested objects, arrays, and explicit empty collections.

1. Prepare the PowerShell session

Complete Authentication and Token Management first. The examples use the $PbrsAccessToken variable from that guide.

$PbrsBaseUrl = "http://localhost:9000"

if ([string]::IsNullOrWhiteSpace($PbrsAccessToken)) {
    throw "Obtain a PBRS access token before continuing."
}

$PbrsHeaders = @{
    Accept        = "application/json"
    Authorization = "bearer $PbrsAccessToken"
}

Replace the base address with your installation's protocol, hostname, and port. Keep /api out of the base address.

Use localhost only when running the example on the PBRS server. Configure HTTPS for network connections.

2. Define recurrence and delivery

The following function builds the common portion of a schedule definition. Each call returns a new definition.

Replace the folder, recipient, start date, and execution time with values appropriate to your installation.

function New-PbrsSingleScheduleDefinition {
    param(
        [Parameter(Mandatory = $true)]
        [string]$Name,

        [Parameter(Mandatory = $true)]
        [string]$FolderPath,

        [Parameter(Mandatory = $true)]
        [string]$StartDate,

        [Parameter(Mandatory = $true)]
        [string]$Recipient
    )

    return @{
        ScheduleName = $Name
        FolderPath   = $FolderPath
        Description  = "Report delivery configured through the API"
        Keywords     = "api,setup-test"
        DataDriven   = $false

        Schedule = @{
            Frequency           = "Daily"
            StartDate           = $StartDate
            ExecutionTime       = "09:00"
            HasEndDate          = $false
            Repeat              = $false
            Enabled             = $false
            DailyRepeatInterval = 1
        }

        EmailDestinations = @(
            @{
                DestinationName = "Test delivery"
                DestinationType = "Email"
                Enabled         = $true
                OutputFormat    = "Acrobat Format (*.pdf)"
                To              = @($Recipient)
                Cc              = @()
                Bcc             = @()
                Subject         = $Name
                Body            = "Attached is the requested report."
                BodyFormat      = "TEXT"
                EmbedReport     = $false
            }
        )

        DiskDestinations = @()
    }
}

$PbrsFolderPath = Read-Host "Existing PBRS folder path"
$PbrsStartDate = Read-Host "Schedule start date (yyyy-MM-dd)"
$PbrsTestRecipient = Read-Host "Controlled test recipient email address"

The schedule is initially disabled through Schedule.Enabled: false. Its email destination is enabled so it can be used when the schedule is executed.

Disabling recurring execution is not a guarantee that the schedule cannot be executed manually or through the API. Keep the test destination controlled.

Recurrence fields

ExecutionTime is not a UTC timestamp. The recurrence model does not provide a timezone parameter. Confirm the intended time and next execution in PBRS.

For weekly or monthly recurrence, provide the corresponding WeeklyOptions or MonthlyOptions. Use explicit day and month selections; empty selections can expand to all days or months.

Repeat controls within-day repetition. Setting it to false does not prevent a daily schedule from recurring on subsequent days.

3. Add the reporting source

Choose one of the following source examples, then continue to the submission step.

These examples use illustrative account identifiers and report locations. Replace them with values from your installation.

Power BI Service report

$PbrsDefinition = New-PbrsSingleScheduleDefinition `
    -Name "API Power BI report" `
    -FolderPath $PbrsFolderPath `
    -StartDate $PbrsStartDate `
    -Recipient $PbrsTestRecipient

$PbrsDefinition.PowerBiAccountId = "7f320302-7ccb-4aba-a052-56197424ab36"
$PbrsDefinition.ObjectType = "REPORT"
$PbrsDefinition.ReportUrl = "https://app.powerbi.com/reportEmbed?reportId=64e25062-4786-43be-bfea-56ec8b9aaeca"
$PbrsDefinition.PowerBiReportName = "Sales overview"
$PbrsDefinition.WorkspaceName = "Sales"
$PbrsDefinition.ApplyBookmark = $false
$PbrsDefinition.ApplyBookmarkState = $false
$PbrsDefinition.BasicFilters = @()
$PbrsDefinition.AdvancedFilters = @()

$PbrsDefinition.RenderingSettings = @{
    MinLoadingTime  = 10
    MaxLoadingTime  = 60
    PageWidth       = 1300
    PageHeight      = 800
    PagesToRender   = ""
    RenderingMethod = 1
}

$PbrsCreateAction = "CreateForPowerBI"
$PbrsReadAction = "Get"
$PbrsUpdateAction = "UpdateForPowerBI"

Use the configured PBRS Power BI account ID and the report URL returned by discovery.

PagesToRender: "" selects all report pages. For a restricted selection, use one-based page numbers or ranges, such as "1,3-5".

The example uses no report filters or bookmarks. Configure them before submission when recipient-specific content is required.

For visual-data Excel output, use the exact output label MS Excel - Data Only (*.xlsx) and the corresponding visual-export settings. Changing the output label alone does not identify the visual to export.

Power BI Paginated Report

$PbrsDefinition = New-PbrsSingleScheduleDefinition `
    -Name "API paginated report" `
    -FolderPath $PbrsFolderPath `
    -StartDate $PbrsStartDate `
    -Recipient $PbrsTestRecipient

$PbrsDefinition.PowerBiAccountId = "7f320302-7ccb-4aba-a052-56197424ab36"
$PbrsDefinition.ObjectType = "PAGINATEDREPORT"
$PbrsDefinition.ReportUrl = "https://app.powerbi.com/groups/24a89913-81fe-4815-a822-8d49cxxxfec1/rdlreports/64e25062-4786-43be-bfea-56ec8b9aaeca"
$PbrsDefinition.PowerBiReportName = "Sales detail"
$PbrsDefinition.WorkspaceName = "Sales"
$PbrsDefinition.UseNativeAPIForRendering = $true

$PbrsDefinition.Parameters = @(
    @{
        ParameterName  = "Region"
        ParameterValue = "West"
        ParameterType  = 0
        IsNull         = $false
    }
)

$PbrsCreateAction = "CreatePaginated"
$PbrsReadAction = "GetPaginated"
$PbrsUpdateAction = "UpdateForPaginated"

Replace the example parameter with parameters accepted by your report. Use an empty array only when no explicit parameters are required.

ParameterValue remains a string, including for numeric, date, and boolean parameter types.

UseNativeAPIForRendering selects a rendering option. Use a configuration supported by your reporting account, deployment, and licensing; setting the flag does not establish those prerequisites.

SSRS report

$PbrsDefinition = New-PbrsSingleScheduleDefinition `
    -Name "API SSRS report" `
    -FolderPath $PbrsFolderPath `
    -StartDate $PbrsStartDate `
    -Recipient $PbrsTestRecipient

$PbrsDefinition.UseSSRSAccount = $true
$PbrsDefinition.SSRSAccountName = "Reporting Server"
$PbrsDefinition.ReportPath = "/Sales/Daily Sales"
$PbrsDefinition.VirtualDirectory = "reports"
$PbrsDefinition.Datasources = @()

$PbrsDefinition.Parameters = @(
    @{
        ParameterName   = "Region"
        ParameterValues = @{
            West = "West"
        }
        IsMultiValue = $false
        IsNull       = $false
    }
)

$PbrsCreateAction = "CreateForSSRS"
$PbrsReadAction = "GetForSSRS"
$PbrsUpdateAction = "UpdateForSSRS"

For this configured-account workflow, supply SSRSAccountName with UseSSRSAccount: true.

Use the report path and virtual directory appropriate to your reporting server. The example value "reports" is not universal.

SSRS parameters use ParameterValues, a string-to-string dictionary. They do not use the paginated report's singular ParameterValue field.

Obtain parameter definitions and supported values through the SSRS metadata operations. Supply datasource overrides when required by the report.

Power BI Report Server

$PbrsDefinition = New-PbrsSingleScheduleDefinition `
    -Name "API PBIRS report" `
    -FolderPath $PbrsFolderPath `
    -StartDate $PbrsStartDate `
    -Recipient $PbrsTestRecipient

$PbrsDefinition.SqlServerAccountId = 1
$PbrsDefinition.ObjectType = "PBIRSITEM"
$PbrsDefinition.ReportPath = "/Sales/Daily Sales"
$PbrsDefinition.ReportTitle = "Daily Sales"
$PbrsDefinition.VirtualDirectory = "reports"
$PbrsDefinition.Parameters = @()

$PbrsDefinition.RenderingSettings = @{
    MinLoadingTime  = 10
    MaxLoadingTime  = 60
    PageWidth       = 1300
    PageHeight      = 800
    PagesToRender   = ""
    RenderingMethod = 1
}

$PbrsCreateAction = "CreatePbirs"
$PbrsReadAction = "GetPBirs"
$PbrsUpdateAction = "UpdateForPbirs"

Replace SqlServerAccountId with the configured account identifier for your PBIRS environment.

The PBIRS request uses SqlServerAccountId and ReportPath. Do not substitute Power BI Service account fields or an SSRS account-name request.

The example assumes no explicit parameters. Add the parameters required by your report using the PBIRS parameter schema.

4. Create the schedule

Review the complete definition before submitting it. Confirm the report, folder, recurrence, recipients, and output settings.

$PbrsSubmittedDefinitionJson = $PbrsDefinition |
    ConvertTo-Json -Depth 30

$PbrsCreated = Invoke-RestMethod `
    -Method Post `
    -Uri "$($PbrsBaseUrl.TrimEnd('/'))/api/SingleSchedule/$PbrsCreateAction" `
    -Headers $PbrsHeaders `
    -ContentType "application/json" `
    -Body $PbrsSubmittedDefinitionJson `
    -TimeoutSec 60 `
    -ErrorAction Stop

if (
    $null -eq $PbrsCreated -or
    $null -eq $PbrsCreated.uniqueid
) {
    throw "No schedule identifier was returned. Reconcile the request before submitting again."
}

$PbrsScheduleId = [long]$PbrsCreated.uniqueid
Write-Host "Created schedule: $PbrsScheduleId"

Single-schedule creation returns an object such as:

{
  "uniqueid": 101
}

Retain the identifier and the submitted definition. Do not confuse uniqueid with a nested recurrence ScheduleId or an execution identifier.

If a creation request times out, search the intended folder and reconcile the outcome before repeating it. Do not assume automatic duplicate prevention.

5. Retrieve and verify the saved schedule

$PbrsSaved = Invoke-RestMethod `
    -Method Get `
    -Uri "$($PbrsBaseUrl.TrimEnd('/'))/api/SingleSchedule/$($PbrsReadAction)?Id=$PbrsScheduleId" `
    -Headers $PbrsHeaders `
    -TimeoutSec 30 `
    -ErrorAction Stop

$PbrsSaved |
    Select-Object uniqueid, ScheduleName, FolderPath

$PbrsSaved.Schedule |
    Select-Object Frequency, StartDate, ExecutionTime, Enabled

Check the source-specific configuration and all destinations. In particular, verify:

• The correct report and configured account.
• Recurrence and enabled state.
• Filters, parameters, bookmarks, and rendering.
• Recipients, attachment format, and destination settings.
• Any destination identifiers assigned during creation.

Open the schedule in PBRS when needed to confirm settings not fully represented in the read response.

Read responses are not complete write templates

Do not assume that a GET response can be submitted unchanged as an update.

Read responses can omit settings, contain masked credentials, or use a different representation. For example, ClientRenderingSettings is not a substitute for the RenderingSettings write model.

Keep the submitted configuration as a baseline, but reconcile it with the current schedule before updating. Other users or applications may have changed the schedule since creation.

6. Update an existing schedule

Updates use the source-specific POST operation and the existing uniqueid.

These operations accept schedule definitions, not arbitrary partial patches. Supplying only the field you want to change can fail or alter other configuration.

Preserve destinations

For all four update operations:

• Include both EmailDestinations and DiskDestinations.
• Supply complete, non-null arrays.
• Preserve the DestinationId of every existing destination you intend to retain.
• Use [] only when the corresponding collection should be empty.
• Preserve recipients, message content, output settings, and other required destination configuration.

Existing destinations absent from the supplied arrays are removed.

Do not replace retained destination IDs with zero. Zero is used for new destination entries and does not identify an existing destination.

An omitted array is not an instruction to preserve the existing destinations.

Preserve report configuration

Power BI updates rebuild filter collections. Include every filter that should remain.

Preserve the intended parameters, bookmarks, rendering settings, recurrence, and source configuration. Do not copy masked passwords from a read response as new credentials.

If a setting cannot be reconstructed reliably, obtain its correct value before submitting the update.

Update the newly created example

The following example applies only to the simple schedule created above: exactly one email destination and no disk destinations.

It retains the original submitted definition, obtains the assigned destination ID, changes the execution time, and leaves recurring execution disabled.

Do not use this shortcut for an existing production schedule or one changed since creation.

$PbrsSaved = Invoke-RestMethod `
    -Method Get `
    -Uri "$($PbrsBaseUrl.TrimEnd('/'))/api/SingleSchedule/$($PbrsReadAction)?Id=$PbrsScheduleId" `
    -Headers $PbrsHeaders `
    -TimeoutSec 30 `
    -ErrorAction Stop

$PbrsSavedEmails = @(
    $PbrsSaved.EmailDestinations |
        Where-Object { $null -ne $_ }
)

$PbrsSavedDisks = @(
    $PbrsSaved.DiskDestinations |
        Where-Object { $null -ne $_ }
)

if (
    $PbrsSavedEmails.Count -ne 1 -or
    $PbrsSavedDisks.Count -ne 0
) {
    throw "The destination configuration differs from this example. Prepare a complete update manually."
}

$PbrsExistingDestinationId = $PbrsSavedEmails[0].DestinationId

if (
    $null -eq $PbrsExistingDestinationId -or
    [long]$PbrsExistingDestinationId -eq 0
) {
    throw "The existing email destination ID could not be established."
}

$PbrsUpdate = $PbrsSubmittedDefinitionJson |
    ConvertFrom-Json

$PbrsUpdate | Add-Member `
    -NotePropertyName uniqueid `
    -NotePropertyValue $PbrsScheduleId `
    -Force

$PbrsUpdate.EmailDestinations[0] | Add-Member `
    -NotePropertyName DestinationId `
    -NotePropertyValue ([long]$PbrsExistingDestinationId) `
    -Force

$PbrsUpdate.Schedule.ExecutionTime = "10:00"
$PbrsUpdate.Schedule.Enabled = $false

$PbrsUpdateJson = $PbrsUpdate |
    ConvertTo-Json -Depth 30

Invoke-RestMethod `
    -Method Post `
    -Uri "$($PbrsBaseUrl.TrimEnd('/'))/api/SingleSchedule/$PbrsUpdateAction" `
    -Headers $PbrsHeaders `
    -ContentType "application/json" `
    -Body $PbrsUpdateJson `
    -TimeoutSec 60 `
    -ErrorAction Stop

A successful full-schedule update returns HTTP 200 with an empty response body. It does not return the updated schedule or a new identifier.

Retrieve the schedule again and verify the changes. Do not treat the absence of a JSON response as an update failure.

Use narrower operations where appropriate

For a parameter-only change to a paginated report, see Update Paginated Report Parameters.

For an email-destination change, see Manage Destinations and Output Settings. Dedicated email operations have their own update rules and do not modify every schedule or destination property.

7. Test before enabling recurrence

1. Retrieve and inspect the saved configuration.
2. Confirm that the delivery destination is controlled.
3. Execute a test using Quick Start: Execute and Monitor a Schedule.
4. Inspect the execution result.
5. Verify report content, formatting, and delivery.
6. Set the intended enabled state using the applicable operation.
7. Confirm the next scheduled execution in PBRS.

Creating or updating a schedule does not itself confirm successful rendering or delivery.

If you enable recurrence through a full update, preserve the complete destination arrays and other configuration just as for any other update.

Create multiple schedules

Bulk creation is available for:

Send a JSON array of complete source-specific definitions. Each definition needs its recurrence and a supported destination.

On complete success, the response is an array of numeric identifiers in input order:

[
  101,
  102
]

This differs from the single-create response, which contains a uniqueid property.

A later failure can leave earlier schedules saved. The batch is not guaranteed to roll back, and a failure does not provide a reliable complete list of partially created identifiers.

Before retrying:

1. Inspect the intended folders or search using explicit identifying keywords.
2. Compare existing schedules with the submitted definitions.
3. Identify which items were created.
4. Submit only the missing work after resolving the failure.

Names and keywords can help reconciliation, but they are not idempotency keys.

Troubleshooting

Check HTTP status before parsing responses. Error responses can vary; do not assume every failure has the same JSON structure.

Next steps

Use Configure Filters, Parameters, Bookmarks, and Rendering to personalize report content.

Continue with Manage Destinations and Output Settings for delivery configuration, and Schedule Lifecycle Reference for source-specific clone, rename, enable, disable, and delete operations.