Manage, Schedule, and Run Recipes with REST APIs

Describe and Discover Recipes

Retrieve all your recipes with the GET wave/recipes endpoint. You can filter the recipes collection returned by:

• format— specifies current Data Prep recipes: (R3) or Data Prep Classic recipes (R2).
  1/wave/recipes?format=R2

• licenseType— specifies the license type: EinsteinAnalytics, Sonic, MulesoftDataPath, or Cdp.
  1/wave/recipes?licenseType=EinsteinAnalytics

• pageSize— the number of items to be returned in the collection for pagination. The minimum is 1, maximum is 200, and default is 25.
  1/wave/recipes?pageSize=50

• q— Use search terms to find recipes by name or label. Individual terms are separated by spaces. A wildcard is automatically appended to the last token in the query string.
  1/wave/recipes?q=My Recipe

• sort— The type of sort order to be applied to the returned collection. Valid values are App, CreatedBy, CreatedDate, LastModified, LastModifiedBy, Mru, Name, and Type.
  1/wave/recipes?sort=Name

Describe an existing recipe by specifying the recipeId (starts with 05vB) and the format of the recipe: R3 or R2.

1/wave/recipes/05vB0000000xxxxxxx?format=R3

The GET request returns a Recipe response, which contains the recipe definition (nodes and UI metadata), schedule attributes, and validation details. It also contains the targetDataflowId, used to run the recipe. For example, GET /wave/recipes/05vB0000000xxxxxxx?format=R3 returns this Recipe JSON response:

1{
2    ...
3    "format" : "R3",
4    "id" : "05vB0000000xxxxxxx",
5    "label" : "MyTestRecipe",
6    "name" : "MyTestRecipe",
7    ...
8    "recipeDefinition" : {
9        ...
10    },
11    "scheduleAttributes" : {
12        ...
13    }, 
14    "targetDataflowId" : "02KB000000xxxxxxxx",
15    ...
16    "validationDetails" : [ ]
17}

Use the Recipe JSON response to work with the recipe as detailed.

Inspect Recipe Nodes

The Recipe Definition contains the recipe name, the recipe API version, the UI metadata for recipe display (used by Data Manager), and a Map of Recipe Node objects.

Here’s a closer look at the Map of Recipe Node objects in the Recipe Definition object from the Recipe JSON response. The example response is a simple recipe that loads data created from the Opportunities sObject, filters the data by Closed Won, and saves the results to a new dataset named Opptys Closed Won.

1{
2    ...
3    "recipeDefinition": {
4        "nodes" : {
5            "LOAD_DATASET0" :  {
6                "action" : "load", 
7                "parameters": {
8                    "dataset" : {
9                        "label" : "Opportunities",
10                        "name" : "opportunity",
11                        "type" : "analyticsDataset"
12                    },
13                    "fields" : ["AccountId", "Amount", "OpenClosedWonLost", ...]
14                },
15                "sources" : []
16            },
17            "FILTER0" : {
18                "action" : "filter",
19                "parameters" : {
20                    "filterExpressions" : [ {
21                        "field" : "OpenClosedWonLost",
22                        "operands" : [ "Closed Won" ],
23                        "operator" : "EQUAL", 
24                        "type" : "TEXT"
25                    } ]
26                },
27                "sources": [ "LOAD_DATASET0" ]
28            },
29            "OUTPUT0" : {
30                "action" : "save", 
31                "parameters": {
32                    "dataset" : {
33                        "folderName" : "SharedApp",
34                        "label" : "Opptys Closed Won",
35                        "name" : "OpptysClosedWon",
36                        "type" : "analyticsDataset"
37                    },
38                    "fields" : []
39                },
40                "sources" : [ "FILTER0" ]
41            }
42        },
43        "ui" : { ... }, 
44        "version" : "52.0"
45    },
46    ...
47}

Each node entry in the map has a string name and Recipe Node. The Recipe Node contains the node action, parameters, and sources. Each node type has different parameters based on the action. For more information on each node type, see the Recipe Node reference.

Delete a Recipe

To delete a recipe, use the DELETE /wave/recipes/<recipeId> endpoint. This action deletes the recipe and any associated dataflow jobs. No request body is required and the response is a success or error message.

Work with Recipe Histories

Each time a user updates and saves a recipe, a version history is created, tracking the changes to the recipe over time. To see all of the histories for a recipe, use the GET /wave/recipes/<recipeId>/histories endpoint.

1{
2    "historyId" : "0RmB0000000xxxxxxx",
3    "historyLabel" : "Reverting to version x"
4}

Schedule a Recipe

While the scheduleAttributes are part of the Recipe, to update a schedule, the /wave/asset/<assetId>/schedule endpoint must be used.

To see the current schedule, use GET /wave/asset/<assetId>/schedule, where <assetId> is the recipe id. The request returns a Schedule response.

To create or update the schedule, use PUT /wave/asset/<assetId>/schedule. See Schedule Dataflows, Recipes, and Data Syncs for example Schedule Input requests.

To delete a schedule, use DELETE /wave/asset/<assetId>/schedule.

Run a Recipe

To run a recipe, with or without a schedule, use the /wave/dataflowjobs POST endpoint.

The POST takes a dataflowId and a command to start the dataflow job. For a recipe, the dataflowId is the targetDataflowId from the Recipe. For recipes, the targetDataflowId starts with 02KB.

1{
2    "dataflowId": "02KB000000xxxxxxxx",
3    "command": "start"
4}

1{
2    "command": "stop"
3}

Recipe Notifications

1{
2    "notificationLevel" : "Always",
3    "longRunningAlertInMins" : 90
4}