Invoking worklets

Invoke worklets to run models & more from a variety of environments

In production, you can invoke a worklet in three different ways:

1. As an API endpoint

2. As a scheduled task

3. In a view

For testing worklets, see testing.

1) API endpoint

You can call the worklet through its auto-generated API endpoint. Think of worklets like AWS Lambda functions but without all of the configuration; the API endpoint is live from the moment the worklet is created.

Example invocation:

curl -X POST https://app.baseten.co/applications/APPLICATION_ID/worklets/WORKLET_ID/invoke \
                                                  -H 'Authorization: Api-Key YOUR_API_KEY' \
                                                  -d '{"worklet_input": WORKLET_INPUT }'

2) Scheduled task

To schedule a worklet, find the worklet in the left sidebar, click the "..." menu, and open the Settings dialog.

Then, enable the "Schedule this worklet" option then choose a frequency and time for the worklet to run.

Schedule frequency and time for a worklet to run

You can see which worklets are scheduled by looking for the clock icon in the worklet list.

One issue that can arise when scheduling worklets: how can you pass an input value to the scheduled run?

The worklet could start with a code block that builds the input for the rest of the worklet to use. But that strategy might not be feasible if the worklet that you want to schedule is also invoked as an API with user-specified input.

In that case, create a second worklet with two blocks:

1. A code block configuring the scheduled input

2. A worklet block calling the original worklet

Then, schedule the second worklet at the desired cadence.

3) In a view

You can invoke worklets directly from views in two ways.

I) From an event handler

You can send a request to a worklet from a view component like a button, and assign its input and output to various view components. Configure this kind of worklet invocation with an event handler.

II) As a binding

You can bind the worklet to the data value of a component (such as Table or JSON Viewer) and assigns its input to various view components. This will result in the worklet being run reactively in response to changes to any input value. Configure this kind of worklet invocation with a binding.

Long-running worklets

Worklet invocations time out after about five minutes by default. If you need longer-running worklets, which is especially useful for scheduled worklets, you can choose to run any worklet asynchronously as a background task.

Long-running API endpoints

If you to invoke a long-running worklet as a background task via an API call, use:

curl -X POST https://app.baseten.co/applications/APPLICATION_ID/worklets/WORKLET_ID/invoke \
                                                  -H 'Authorization: Api-Key YOUR_API_KEY' \
                                                  -d '{"worklet_input": WORKLET_INPUT, "async": true }'

Worklets have a cold start. The first invocation of a worklet can take a few seconds to wake up if the worklet has not been run recently.

You'll get back information about your worklet run:

{
    "success": true,
    "scheduled_worklet_run_id": "RUN_ID",
    "message": "Worklet scheduled for background execution"
}

While your worklet is running, you can poll it with:

curl -X POST https://app.baseten.co/applications/APPLICATION_ID/worklets/WORKLET_ID/RUN_ID \
                                                  -H 'Authorization: Api-Key YOUR_API_KEY' 

You'll get back information about your run:

{
    "status": "SUCCEEDED",
    "message": "Worklet has finished executing successfully",
    "worklet_output": "woke up!",
    "latency_ms": 97
}

When status is SUCCEEDED, the worklet run has completed and you can read the worklet_output field for your results.

Long-running scheduled tasks

To configure a worklet to run in the background, find the worklet in the left sidebar, click the "..." menu, and open the Settings dialog.

Toggle on "Run worklet as background task" and your worklet will be executed asynchronously. This bypasses the default timeout as your long-running worklet won't block other tasks.

A worklet configured to run as a background task