Share via

Scheduled Actions - Create Or Update By Scope

Service:
Cost Management
API Version:
2025-03-01

Create or update a shared scheduled action within the given scope.

PUT https://management.azure.com/{scope}/providers/Microsoft.CostManagement/scheduledActions/{name}?api-version=2025-03-01

URI Parameters

Name In Required Type Description
name
 path True

string

Scheduled action name.
scope
 path True

string

The scope associated with scheduled action operations. This includes 'subscriptions/{subscriptionId}' for subscription scope, 'subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}' for resourceGroup scope, 'providers/Microsoft.Billing/billingAccounts/{billingAccountId}' for Billing Account scope, 'providers/Microsoft.Billing/billingAccounts/{billingAccountId}/departments/{departmentId}' for Department scope, 'providers/Microsoft.Billing/billingAccounts/{billingAccountId}/enrollmentAccounts/{enrollmentAccountId}' for EnrollmentAccount scope, 'providers/Microsoft.Billing/billingAccounts/{billingAccountId}/billingProfiles/{billingProfileId}' for BillingProfile scope, 'providers/Microsoft.Billing/billingAccounts/{billingAccountId}/invoiceSections/{invoiceSectionId}' for InvoiceSection scope, 'providers/Microsoft.CostManagement/externalBillingAccounts/{externalBillingAccountName}' for External Billing Account scope and 'providers/Microsoft.CostManagement/externalSubscriptions/{externalSubscriptionName}' for External Subscription scope. Note: Insight Alerts are only available on subscription scope.
api-version
 query True

string

minLength: 1

The API version to use for this operation.

Request Header

Name Required Type Description
If-Match

string

ETag of the Entity. Not required when creating an entity. Optional when updating an entity and can be specified to achieve optimistic concurrency.

Request Body

Name Required Type Description
properties.displayName True

string

Scheduled action name.
properties.notification True

NotificationProperties

Notification properties based on scheduled action kind.
properties.schedule True

ScheduleProperties

Schedule of the scheduled action.
properties.status True

ScheduledActionStatus

Status of the scheduled action.
properties.viewId True

string

Cost analysis viewId used for scheduled action. For example, '/providers/Microsoft.CostManagement/views/swaggerExample'
kind

ScheduledActionKind

Kind of the scheduled action.
properties.fileDestination

FileDestination

Destination format of the view data. This is optional.
properties.notificationEmail

string

Email address of the point of contact that should get the unsubscribe requests and notification emails.
properties.scope

string

For private scheduled action(Create or Update), scope will be empty.
For shared scheduled action(Create or Update By Scope), Cost Management scope can be 'subscriptions/{subscriptionId}' for subscription scope, 'subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}' for resourceGroup scope, 'providers/Microsoft.Billing/billingAccounts/{billingAccountId}' for Billing Account scope, 'providers/Microsoft.Billing/billingAccounts/{billingAccountId}/departments/{departmentId}' for Department scope, 'providers/Microsoft.Billing/billingAccounts/{billingAccountId}/enrollmentAccounts/{enrollmentAccountId}' for EnrollmentAccount scope, 'providers/Microsoft.Billing/billingAccounts/{billingAccountId}/billingProfiles/{billingProfileId}' for BillingProfile scope, 'providers/Microsoft.Billing/billingAccounts/{billingAccountId}/invoiceSections/{invoiceSectionId}' for InvoiceSection scope, '/providers/Microsoft.CostManagement/externalBillingAccounts/{externalBillingAccountName}' for ExternalBillingAccount scope, and '/providers/Microsoft.CostManagement/externalSubscriptions/{externalSubscriptionName}' for ExternalSubscription scope.

Responses

Name Type Description
200 OK

ScheduledAction

OK. The request has succeeded.
201 Created

ScheduledAction

Created.
Other Status Codes

ErrorResponseWithNestedDetails

Error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
user_impersonation impersonate your user account

Examples

CreateOrUpdateInsightAlertScheduledActionByScope
CreateOrUpdateScheduledActionByScope

CreateOrUpdateInsightAlertScheduledActionByScope

Sample request

PUT https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/scheduledActions/dailyAnomalyByResource?api-version=2025-03-01


{
  "kind": "InsightAlert",
  "properties": {
    "displayName": "Daily anomaly by resource",
    "notification": {
      "to": [
        "user@gmail.com",
        "team@gmail.com"
      ],
      "subject": "Cost anomaly detected in the resource"
    },
    "schedule": {
      "frequency": "Daily",
      "startDate": "2020-06-19T22:21:51.1287144Z",
      "endDate": "2021-06-19T22:21:51.1287144Z"
    },
    "status": "Enabled",
    "viewId": "/providers/Microsoft.CostManagement/views/swaggerExample"
  }
}

Sample response

Status code:
201 
{
  "id": "subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/scheduledActions/dailyAnomalyByResource",
  "name": "dailyAnomalyByResource",
  "type": "Microsoft.CostManagement/ScheduledActions",
  "kind": "InsightAlert",
  "eTag": "\"1d4ff9fe66f1d10\"",
  "systemData": {
    "createdBy": "testuser",
    "createdByType": "User",
    "createdAt": "2020-06-18T22:21:51.1287144Z",
    "lastModifiedBy": "testuser",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2020-06-18T22:21:51.1287144Z"
  },
  "properties": {
    "displayName": "Daily anomaly by resource",
    "fileDestination": {
      "fileFormats": []
    },
    "notification": {
      "to": [
        "user@gmail.com",
        "team@gmail.com"
      ],
      "subject": "Cost anomaly detected in the resource"
    },
    "schedule": {
      "frequency": "Daily",
      "startDate": "2020-06-19T22:21:51.1287144Z",
      "endDate": "2021-06-19T22:21:51.1287144Z"
    },
    "scope": "subscriptions/00000000-0000-0000-0000-000000000000",
    "status": "Enabled",
    "viewId": "/providers/Microsoft.CostManagement/views/swaggerExample"
  }
}
Status code:
200 
{
  "id": "subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/scheduledActions/dailyAnomalyByResource",
  "name": "dailyAnomalyByResource",
  "type": "Microsoft.CostManagement/ScheduledActions",
  "kind": "InsightAlert",
  "eTag": "\"1d4ff9fe66f1d10\"",
  "systemData": {
    "createdBy": "testuser",
    "createdByType": "User",
    "createdAt": "2020-06-18T22:21:51.1287144Z",
    "lastModifiedBy": "testuser",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2020-06-19T22:21:51.1287144Z"
  },
  "properties": {
    "displayName": "Daily anomaly by resource",
    "fileDestination": {
      "fileFormats": []
    },
    "notification": {
      "to": [
        "user@gmail.com",
        "team@gmail.com"
      ],
      "subject": "Cost anomaly detected in the resource"
    },
    "scope": "subscriptions/00000000-0000-0000-0000-000000000000",
    "schedule": {
      "frequency": "Daily",
      "startDate": "2020-06-19T22:21:51.1287144Z",
      "endDate": "2021-06-19T22:21:51.1287144Z"
    },
    "status": "Enabled",
    "viewId": "/providers/Microsoft.CostManagement/views/swaggerExample"
  }
}

CreateOrUpdateScheduledActionByScope

Sample request

PUT https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/scheduledActions/monthlyCostByResource?api-version=2025-03-01


{
  "kind": "Email",
  "properties": {
    "displayName": "Monthly Cost By Resource",
    "fileDestination": {
      "fileFormats": [
        "Csv"
      ]
    },
    "notification": {
      "to": [
        "user@gmail.com",
        "team@gmail.com"
      ],
      "subject": "Cost by resource this month"
    },
    "schedule": {
      "frequency": "Monthly",
      "weeksOfMonth": [
        "First",
        "Third"
      ],
      "daysOfWeek": [
        "Monday"
      ],
      "hourOfDay": 10,
      "startDate": "2020-06-19T22:21:51.1287144Z",
      "endDate": "2021-06-19T22:21:51.1287144Z"
    },
    "status": "Enabled",
    "viewId": "/providers/Microsoft.CostManagement/views/swaggerExample"
  }
}

Sample response

Status code:
201 
{
  "id": "subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/scheduledActions/monthlyCostByResource",
  "name": "monthlyCostByResource",
  "type": "Microsoft.CostManagement/ScheduledActions",
  "kind": "Email",
  "eTag": "\"1d4ff9fe66f1d10\"",
  "systemData": {
    "createdBy": "testuser",
    "createdByType": "User",
    "createdAt": "2020-06-18T22:21:51.1287144Z",
    "lastModifiedBy": "testuser",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2020-06-18T22:21:51.1287144Z"
  },
  "properties": {
    "displayName": "Monthly Cost By Resource",
    "fileDestination": {
      "fileFormats": [
        "Csv"
      ]
    },
    "notification": {
      "to": [
        "user@gmail.com",
        "team@gmail.com"
      ],
      "subject": "Cost by resource this month"
    },
    "schedule": {
      "frequency": "Monthly",
      "weeksOfMonth": [
        "First",
        "Third"
      ],
      "daysOfWeek": [
        "Monday"
      ],
      "hourOfDay": 10,
      "startDate": "2020-06-19T22:21:51.1287144Z",
      "endDate": "2021-06-19T22:21:51.1287144Z"
    },
    "scope": "subscriptions/00000000-0000-0000-0000-000000000000",
    "status": "Enabled",
    "viewId": "/providers/Microsoft.CostManagement/views/swaggerExample"
  }
}
Status code:
200 
{
  "id": "subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/scheduledActions/monthlyCostByResource",
  "name": "monthlyCostByResource",
  "type": "Microsoft.CostManagement/ScheduledActions",
  "kind": "Email",
  "eTag": "\"1d4ff9fe66f1d10\"",
  "systemData": {
    "createdBy": "testuser",
    "createdByType": "User",
    "createdAt": "2020-06-18T22:21:51.1287144Z",
    "lastModifiedBy": "testuser",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2020-06-19T22:21:51.1287144Z"
  },
  "properties": {
    "displayName": "Monthly Cost By Resource",
    "notification": {
      "to": [
        "user@gmail.com",
        "team@gmail.com"
      ],
      "subject": "Cost by resource this month"
    },
    "scope": "subscriptions/00000000-0000-0000-0000-000000000000",
    "schedule": {
      "frequency": "Monthly",
      "weeksOfMonth": [
        "First",
        "Third"
      ],
      "daysOfWeek": [
        "Monday"
      ],
      "hourOfDay": 10,
      "startDate": "2020-06-19T22:21:51.1287144Z",
      "endDate": "2021-06-19T22:21:51.1287144Z"
    },
    "status": "Enabled",
    "viewId": "/providers/Microsoft.CostManagement/views/swaggerExample"
  }
}

Definitions

Name Description
createdByType

The type of identity that created the resource.
DaysOfWeek

Days of Week.
ErrorDetailsWithNestedDetails

The details of the error.
ErrorResponseWithNestedDetails

Error response indicates that the service is not able to process the incoming request. The reason is provided in the error message.

Some Error responses:

  • 429 TooManyRequests - Request is throttled. Retry after waiting for the time specified in the "x-ms-ratelimit-microsoft.consumption-retry-after" header.

  • 503 ServiceUnavailable - Service is temporarily unavailable. Retry after waiting for the time specified in the "Retry-After" header.
FileDestination

Destination of the view data. This is optional. Currently only CSV format is supported.
FileFormat

Destination of the view data. Currently only CSV format is supported.
NotificationProperties

The properties of the scheduled action notification.
ScheduledAction

Scheduled action definition.
ScheduledActionKind

Kind of the scheduled action.
ScheduledActionStatus

Status of the scheduled action.
ScheduleFrequency

Frequency of the schedule.
ScheduleProperties

The properties of the schedule.
systemData

Metadata pertaining to creation and last modification of the resource.
WeeksOfMonth

Weeks of month.

createdByType

Enumeration

The type of identity that created the resource.

Value Description
User
Application
ManagedIdentity
Key

DaysOfWeek

Enumeration

Days of Week.

Value Description
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Sunday

ErrorDetailsWithNestedDetails

Object

The details of the error.

Name Type Description
code

string

Error code.
details

ErrorDetailsWithNestedDetails[]

The additional details of the error.
message

string

Error message indicating why the operation failed.

ErrorResponseWithNestedDetails

Object

Error response indicates that the service is not able to process the incoming request. The reason is provided in the error message.

Some Error responses:

  • 429 TooManyRequests - Request is throttled. Retry after waiting for the time specified in the "x-ms-ratelimit-microsoft.consumption-retry-after" header.

  • 503 ServiceUnavailable - Service is temporarily unavailable. Retry after waiting for the time specified in the "Retry-After" header.

Name Type Description
error

ErrorDetailsWithNestedDetails

The details of the error.

FileDestination

Object

Destination of the view data. This is optional. Currently only CSV format is supported.

Name Type Description
fileFormats

FileFormat[]

Destination of the view data. Currently only CSV format is supported.

FileFormat

Enumeration

Destination of the view data. Currently only CSV format is supported.

Value Description
Csv

NotificationProperties

Object

The properties of the scheduled action notification.

Name Type Description
language

string

Locale of the email.
message

string

Optional message to be added in the email. Length is limited to 250 characters.
regionalFormat

string

Regional format used for formatting date/time and currency values in the email.
subject

string

Subject of the email. Length is limited to 70 characters.
to

string[]

pattern: ^[A-Za-z0-9._%+-]+@(?:[A-Za-z0-9-]+\.)+[A-Za-z]{2,}$

Array of email addresses.

ScheduledAction

Object

Scheduled action definition.

Name Type Description
eTag

string

Resource Etag. For update calls, eTag is optional and can be specified to achieve optimistic concurrency. Fetch the resource's eTag by doing a 'GET' call first and then including the latest eTag as part of the request body or 'If-Match' header while performing the update. For create calls, eTag is not required.
id

string

Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
kind

ScheduledActionKind

Kind of the scheduled action.
name

string

The name of the resource
properties.displayName

string

Scheduled action name.
properties.fileDestination

FileDestination

Destination format of the view data. This is optional.
properties.notification

NotificationProperties

Notification properties based on scheduled action kind.
properties.notificationEmail

string

Email address of the point of contact that should get the unsubscribe requests and notification emails.
properties.schedule

ScheduleProperties

Schedule of the scheduled action.
properties.scope

string

For private scheduled action(Create or Update), scope will be empty.
For shared scheduled action(Create or Update By Scope), Cost Management scope can be 'subscriptions/{subscriptionId}' for subscription scope, 'subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}' for resourceGroup scope, 'providers/Microsoft.Billing/billingAccounts/{billingAccountId}' for Billing Account scope, 'providers/Microsoft.Billing/billingAccounts/{billingAccountId}/departments/{departmentId}' for Department scope, 'providers/Microsoft.Billing/billingAccounts/{billingAccountId}/enrollmentAccounts/{enrollmentAccountId}' for EnrollmentAccount scope, 'providers/Microsoft.Billing/billingAccounts/{billingAccountId}/billingProfiles/{billingProfileId}' for BillingProfile scope, 'providers/Microsoft.Billing/billingAccounts/{billingAccountId}/invoiceSections/{invoiceSectionId}' for InvoiceSection scope, '/providers/Microsoft.CostManagement/externalBillingAccounts/{externalBillingAccountName}' for ExternalBillingAccount scope, and '/providers/Microsoft.CostManagement/externalSubscriptions/{externalSubscriptionName}' for ExternalSubscription scope.
properties.status

ScheduledActionStatus

Status of the scheduled action.
properties.viewId

string

Cost analysis viewId used for scheduled action. For example, '/providers/Microsoft.CostManagement/views/swaggerExample'
systemData

systemData

Kind of the scheduled action.
type

string

The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

ScheduledActionKind

Enumeration

Kind of the scheduled action.

Value Description
Email

Cost analysis data will be emailed.
InsightAlert

Cost anomaly information will be emailed. Available only on subscription scope at daily frequency. If no anomaly is detected on the resource, an email won't be sent.

ScheduledActionStatus

Enumeration

Status of the scheduled action.

Value Description
Enabled

Scheduled action is saved and will be run.
Expired

Scheduled action is expired.
Disabled

Scheduled action is saved but will not be run.

ScheduleFrequency

Enumeration

Frequency of the schedule.

Value Description
Daily

Cost analysis data will be emailed every day.
Weekly

Cost analysis data will be emailed every week.
Monthly

Cost analysis data will be emailed every month.

ScheduleProperties

Object

The properties of the schedule.

Name Type Description
dayOfMonth

integer (int32)

UTC day on which cost analysis data will be emailed. Must be between 1 and 31. This property is applicable when frequency is Monthly and overrides weeksOfMonth or daysOfWeek.
daysOfWeek

DaysOfWeek[]

Day names in english on which cost analysis data will be emailed. This property is applicable when frequency is Weekly or Monthly.
endDate

string (date-time)

The end date and time of the scheduled action (UTC).
frequency

ScheduleFrequency

Frequency of the schedule.
hourOfDay

integer (int32)

UTC time at which cost analysis data will be emailed.
startDate

string (date-time)

The start date and time of the scheduled action (UTC).
weeksOfMonth

WeeksOfMonth[]

Weeks in which cost analysis data will be emailed. This property is applicable when frequency is Monthly and used in combination with daysOfWeek.

systemData

Object

Metadata pertaining to creation and last modification of the resource.

Name Type Description
createdAt

string (date-time)

The timestamp of resource creation (UTC).
createdBy

string

The identity that created the resource.
createdByType

createdByType

The type of identity that created the resource.
lastModifiedAt

string (date-time)

The timestamp of resource last modification (UTC)
lastModifiedBy

string

The identity that last modified the resource.
lastModifiedByType

createdByType

The type of identity that last modified the resource.

WeeksOfMonth

Enumeration

Weeks of month.

Value Description
First
Second
Third
Fourth
Last