Version 4.0.24.12
Run a Scheduled Plan By Id Immediately
This function creates a run-once schedule plan based on an existing scheduled plan, applies modifications (if any) to the new scheduled plan, and runs the new schedule plan immediately. This can be useful for testing modifications to an existing scheduled plan before committing to a production schedule.
This function internally performs the following operations:
- Copies the properties of the existing scheduled plan into a new scheduled plan
- Copies any properties passed in the JSON body of this request into the new scheduled plan (replacing the original values)
- Creates the new scheduled plan
- Runs the new scheduled plan
The original scheduled plan is not modified by this operation. Admins can create, modify, and run scheduled plans on behalf of other users by specifying a user id. Non-admins can only create, modify, and run their own scheduled plans.
Email Permissions:
For details about permissions required to schedule delivery to email and the safeguards Looker offers to protect against sending to unauthorized email destinations, see Email Domain Allow List for Scheduled Looks.
Scheduled Plan Destination Formats
Scheduled plan destinations must specify the data format to produce and send to the destination.
Formats:
| format | Description |
|---|---|
| json | A JSON object containing a data property which contains an array of JSON objects, one per row. No metadata. |
| json_detail | Row data plus metadata describing the fields, pivots, table calcs, and other aspects of the query |
| inline_json | Same as the JSON format, except that the data property is a string containing JSON-escaped row data. Additional properties describe the data operation. This format is primarily used to send data to web hooks so that the web hook doesn't have to re-encode the JSON row data in order to pass it on to its ultimate destination. |
| csv | Comma separated values with a header |
| txt | Tab separated values with a header |
| html | Simple html |
| xlsx | MS Excel spreadsheet |
| wysiwyg_pdf | Dashboard rendered in a tiled layout to produce a PDF document |
| assembled_pdf | Dashboard rendered in a single column layout to produce a PDF document |
| wysiwyg_png | Dashboard rendered in a tiled layout to produce a PNG image |
Valid formats vary by destination type and source object. wysiwyg_pdf is only valid for dashboards, for example.
This API is rate limited to prevent it from being used for relay spam or DoS attacks
Request
POST
/scheduled_plans/{scheduled_plan_id}/run_once
Datatype
Description
Request
path
Expand HTTP Path definition...
scheduled_plan_id
Id of schedule plan to copy and run
body
Expand HTTP Body definition...
body
Property values to apply to the newly copied scheduled plan before running it
Expand WriteScheduledPlan definition...
name
Name of this scheduled plan
user_id
User Id which owns this scheduled plan
run_as_recipient
Whether schedule is run as recipient (only applicable for email recipients)
enabled
Whether the ScheduledPlan is enabled
look_id
Id of a look
dashboard_id
Id of a dashboard
lookml_dashboard_id
Id of a LookML dashboard
filters_string
Query string to run look or dashboard with
dashboard_filters
(DEPRECATED) Alias for filters_string field
require_results
Delivery should occur if running the dashboard or look returns results
require_no_results
Delivery should occur if the dashboard look does not return results
require_change
Delivery should occur if data have changed since the last run
send_all_results
Will run an unlimited query and send all results.
crontab
Vixie-Style crontab specification when to run
datagroup
Name of a datagroup; if specified will run when datagroup triggered (can't be used with cron string)
timezone
Timezone for interpreting the specified crontab (default is Looker instance timezone)
query_id
Query id
scheduled_plan_destination
run_once
Whether the plan in question should only be run once (usually for testing)
include_links
Whether links back to Looker should be included in this ScheduledPlan
custom_url_base
Custom url domain for the scheduled entity
custom_url_params
Custom url path and parameters for the scheduled entity
custom_url_label
Custom url label for the scheduled entity
show_custom_url
Whether to show custom link back instead of standard looker link
pdf_paper_size
The size of paper the PDF should be formatted to fit. Valid values are: "letter", "legal", "tabloid", "a0", "a1", "a2", "a3", "a4", "a5".
pdf_landscape
Whether the PDF should be formatted for landscape orientation
embed
Whether this schedule is in an embed context or not
color_theme
Color scheme of the dashboard if applicable
long_tables
Whether or not to expand table vis to full length
inline_table_width
The pixel width at which we render the inline table visualizations
Response
200: Scheduled Plan
Datatype
Description
(object)
name
Name of this scheduled plan
user_id
User Id which owns this scheduled plan
run_as_recipient
Whether schedule is run as recipient (only applicable for email recipients)
enabled
Whether the ScheduledPlan is enabled
look_id
Id of a look
dashboard_id
Id of a dashboard
lookml_dashboard_id
Id of a LookML dashboard
filters_string
Query string to run look or dashboard with
dashboard_filters
(DEPRECATED) Alias for filters_string field
require_results
Delivery should occur if running the dashboard or look returns results
require_no_results
Delivery should occur if the dashboard look does not return results
require_change
Delivery should occur if data have changed since the last run
send_all_results
Will run an unlimited query and send all results.
crontab
Vixie-Style crontab specification when to run
datagroup
Name of a datagroup; if specified will run when datagroup triggered (can't be used with cron string)
timezone
Timezone for interpreting the specified crontab (default is Looker instance timezone)
query_id
Query id
scheduled_plan_destination
Expand ScheduledPlanDestination definition...
id
lock
Unique Id
scheduled_plan_id
Id of a scheduled plan you own
format
The data format to send to the given destination. Supported formats vary by destination, but include: "txt", "csv", "inline_json", "json", "json_detail", "xlsx", "html", "wysiwyg_pdf", "assembled_pdf", "wysiwyg_png"
apply_formatting
Are values formatted? (containing currency symbols, digit separators, etc.
apply_vis
Whether visualization options are applied to the results.
address
Address for recipient. For email e.g. 'user@example.com'. For webhooks e.g. 'https://example.domain/path'. For Amazon S3 e.g. 's3://bucket-name/path/'. For SFTP e.g. 'sftp://host-name/path/'.
looker_recipient
lock
Whether the recipient is a Looker user on the current instance (only applicable for email recipients)
type
Type of the address ('email', 'webhook', 's3', or 'sftp')
parameters
JSON object containing parameters for external scheduling. For Amazon S3, this requires keys and values for access_key_id and region. For SFTP, this requires a key and value for username.
secret_parameters
(Write-Only) JSON object containing secret parameters for external scheduling. For Amazon S3, this requires a key and value for secret_access_key. For SFTP, this requires a key and value for password.
message
Optional message to be included in scheduled emails
run_once
Whether the plan in question should only be run once (usually for testing)
include_links
Whether links back to Looker should be included in this ScheduledPlan
custom_url_base
Custom url domain for the scheduled entity
custom_url_params
Custom url path and parameters for the scheduled entity
custom_url_label
Custom url label for the scheduled entity
show_custom_url
Whether to show custom link back instead of standard looker link
pdf_paper_size
The size of paper the PDF should be formatted to fit. Valid values are: "letter", "legal", "tabloid", "a0", "a1", "a2", "a3", "a4", "a5".
pdf_landscape
Whether the PDF should be formatted for landscape orientation
embed
Whether this schedule is in an embed context or not
color_theme
Color scheme of the dashboard if applicable
long_tables
Whether or not to expand table vis to full length
inline_table_width
The pixel width at which we render the inline table visualizations
id
lock
Unique Id
created_at
lock
Date and time when ScheduledPlan was created
updated_at
lock
Date and time when ScheduledPlan was last updated
title
lock
Title
user
lock
User who owns this ScheduledPlan
Expand UserPublic definition...
can
lock
Operations the current user is able to perform on this object
id
lock
Unique Id
first_name
lock
First Name
last_name
lock
Last Name
display_name
lock
Full name for display (available only if both first_name and last_name are set)
avatar_url
lock
URL for the avatar image (may be generic)
url
lock
Link to get this item
next_run_at
lock
When the ScheduledPlan will next run (null if running once)
last_run_at
lock
When the ScheduledPlan was last run
can
lock
Operations the current user is able to perform on this object
400: Bad Request
Datatype
Description
(object)
message
lock
Error details
documentation_url
lock
Documentation link
404: Not Found
Datatype
Description
(object)
message
lock
Error details
documentation_url
lock
Documentation link
409: Resource Already Exists
Datatype
Description
(object)
message
lock
Error details
documentation_url
lock
Documentation link
422: Validation Error
Datatype
Description
(object)
message
lock
Error details
errors
Expand ValidationErrorDetail definition...
field
lock
Field with error
code
lock
Error code
message
lock
Error info message
documentation_url
lock
Documentation link
documentation_url
lock
Documentation link
429: Too Many Requests
Datatype
Description
(object)
message
lock
Error details
documentation_url
lock
Documentation link