RunAt.dev Task Execution

RunAt.dev allows developers to schedule "tasks" for any specific point in time, down to a specific millisecond. A task is simply an API call that is scheduled.

This document describes the task lifecycle and how tasks execute. To schedule tasks, read our API reference.

Request Structure

Requests to schedule new tasks (/v1/schedule API), largely act like a proxy. RunAt.dev will hold your request, then make it on behalf of you at the time specified in the original request.

Below describes what outgoing, scheduled requests look like.

HTTP Method

The HTTP method used to schedule a task will be the HTTP method used in the outgoing request. All HTTP methods used in the /v1/schedule endpoint function identically.

e.g., if a task was scheduled via PUT, RunAt.dev will make a PUT request when the task runs.

Headers

• All headers included in requests to schedule tasks will be included in scheduled requests, except your API key at X-RunAt-API-Key
• A header X-RunAt-Scheduled-At will be appended to scheduled requests, which is the milliseconds since epoch this task had been scheduled at. This header may be checked to determine when this task was supposed to run, or capture & log latency.
• A header X-RunAt-Task-Id will be appended to scheduled requests, which is the id of the task making this request. This header may be used to determine which task ran.
• Additional headers may be appended, either by us, or our hosting providers

RunAt.dev intends to add new, additional utility headers to scheduled task requests, so we don't recommend strict validation on request headers.

Body

Any body content, of any content type, is accepted in schedule task requests, as long as it is below 100KiB.

Any body content sent in requests will be sent in requests when the task runs.

Retires

A task is considered successful if it runs and returns a 2xx HTTP status code.

A task is considered failed if any other HTTP codes are returned, or the requested URL takes longer than 10 seconds to respond, which is considered a timeout.

Tasks that have been failed retry that same request up to 6 additional times, with an exponential backoff. After the 7th and final unsuccessful attempt, the task is considered failed and will be deleted.

Timeouts

RunAt.dev is not meant to wait on long-running tasks, so expects all requests to resolve within 10 seconds.

If your task triggers a long-running process that must execute longer than 10 seconds, we recommend returning a prompt HTTP response to RunAt.dev and handling that longer-running process asynchronously.

Task Timing

RunAt.dev is optimized to make your scheduled timings as accurate as possible. Read more about how we achieve this in our platform here.

In general, the scheduled time is the time that RunAt.dev will start to process process your request. You should expect 10's of milliseconds for us to send your request, and some additional latency for this request to cross the internet, to get to your specified URL. Because of this, RunAt.dev cannot guarantee that your task runs exactly at the time scheduled.

Example Task Execution Requests

Below is an example request lifecyle: scheduling a task, then RunAt.dev executing that scheduled task.

In this example, we'll schedule a POST request for 60 seconds in the future, with the task id example-test, to the domain, https://webhook.site, including the body { "test": 123 }.

curl -X 'POST' \
  'https://api.runat.dev/v1/schedule?url=https%3A%2F%2Fwebhook.site%2F2990d73e-2a43-48fc-8d22-b289fe2703cd&in_ms=60000&task_id=example-test' \
  -H 'accept: application/json' \
  -H 'X-RunAt-API-Key: runat_XXXXXX' \
  -H 'Content-Type: */*' \
  -d '{ "test": 123 }'

Response:

{
  "task_id": "example-test",
  "scheduled_at_ms": 1716686297254,
  "created_at": "2024-05-26T01:17:17.254Z"
}

Equivalent request RunAt.dev would send at execution (60 seconds later):

curl -X 'POST' 'https://webhook.site/2990d73e-2a43-48fc-8d22-b289fe2703cd'
-H 'connection: close'
-H 'x-runat-task-id: example-test'
-H 'x-runat-scheduled-at: 1716686297254'
-H 'accept: application/json'
-H 'content-type: */*'
-H 'content-length: 15'
-H 'accept-encoding: gzip'
-H 'host: webhook.site'
-d $'{ "test": 123 }'