Introduction

Repeater.dev lets you execute tasks at a predefined time (or on a recurring basis). Repeater is accessed through a GraphQL API available at https://api.repeater.dev/graphql If you have a client that is capable of doing so, you can issue an introspection query against that endpoint and receive a list of query and mutations that you can perform.

We also have an official Javascript library, repeaterdev-js, that lets you skip worrying about your own GraphQL calls. There are example code snippets below for both raw GraphQL queries and library usage samples.

A typical workflow with Repeater may look something like:

  1. Create an Application
  2. Create one or more Jobs to be run in the future
  3. At some point after a Job has run, check the JobResult to make sure it completed successfully (or if it failed, why?)

Getting Started

Before you can use the API you'll need to create an account at https://repeater.dev Once you've logged in you'll need to create an Application which will serve as the owner of any Jobs you create.

The random token that's generated along with your Application will serve as your access token for the API.

New application form

Application token

Authentication

Once you have the token from your Application you must include that in the header of every GraphQL call in the form of a Bearer token.

If you are using the repeaterdev-js library you create a new instance using your token as the first argument.

Applications

Applications serve as a top-level "container" for your Jobs. If you have two deployed webapps that need scheduled job processing, you would an Application for each, each with a unique name.

Creating an Application also generates a unique token. That token is used to authenticate each GraphQL API request.

Currently you can only create Applications via the https://repeater.dev UI. However you can request Application details as a field on other queries, like Jobs.

Fields

name String Name of the Application
token StringUsed to authenticate GraphQL requests.
createdAt ISO8601 Timestamp When this Application was created
updatedAt ISO8601 Timestamp When this Application was last updated. Creating/updating Jobs for this Application also updates this value.
jobsCount Integer How many total Jobs belong to this Application
scheduledJobsCount Integer How many Jobs belonging to this Application are scheduled to be run in the future

Jobs

Jobs are the main components of Repeater. A Job will contain a URL to hit somewhere on the internet and record the response as a JobResult. Jobs can be run once or on a recurring basis.

A Job must have a unique name (unique among its parent Application) which will act as its unique identifier for all query and mutation operations.

Fields

name String Unique name for this Job
enabled Boolean Whether this Job is enabled and will run at the specified time(s)
endpoint String The URL that will be requested. The request engine will follow redirects (3XX status codes) until a 2XX or 4XX-5XX code is returned.
verb String The HTTP verb to make the request with. One of GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
headers String Javascript object containing any headers to set on the request
body String Any body to send along with the request
retryable Boolean Whether the Job should be retried if it fails. If so, the Job is tried again on a backoff schedule of N ** 4 seconds, where N is the number of previous attempts. Maximum of 24 retries. If the Job is recurring then retrying will follow this schedule, otherwise the next run of a failed Job will occur on the regular schedule.
runAt ISO8601 Timestamp An ISO8601 timestamp of when the Job should run. For recurring Jobs, this is the time of the first run. Ex: 2020-08-22T12:34:56Z
runEvery ISO8601 Duration An ISO8601 duration of the recurring schedule for the Job. Ex: P1D would run once per day, starting at the runAt time. If null then the Job will only run once at the runAt time.
createdAt ISO8601 Timestamp An ISO8601 timestamp of when the Job was created.
updatedAt ISO8601 Timestamp An ISO8601 timestamp of when the Job was last updated (when the Job runs this value will be also be updated).
lastRunAt ISO8601 Timestamp The last time a Runner for this Job was run. Will be null if the Job has not run yet.
nextRunAt ISO8601 Timestamp An ISO8601 timestamp of when this Job will run next. Will be null if the Job is not enabled or has already run.
successCount Integer If any JobResults are present, the count that were successes (HTTP response code < 400)
failureCount Integer If any JobResults are present, the count that were failures (HTTP response code >= 400)
application Application Details for the Application this Job is attached to. See Application fields.
jobResults [JobResult] Details for the JobResults attached to this Job. See JobResult fields.
runners [Runner] Any Runners that are scheduled to run. See Runner fields.

jobs query

Returns all Jobs for the Application used to authenticate.

job query

Returns details for the given Job name.

Arguments

name (required) String Name of the Job

createJob mutation

Creates a Job. If a value is given for runEvery then the Job will run on that recurring schedule. Otherwise it will only run once at runAt

Fields

applicationName (optional) String The name of the Application to create this job for. If null then it uses whatever Application token was used when authenticating.
name (required) String Unique name for this Job
enabled (optional, default true) Boolean Whether this Job is enabled and will run at the specified time(s)
endpoint (required) String The URL to request
verb (required) String The HTTP verb to make the request with. One of GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
headers (optional) String Any headers to send along with the request. Use stringified JSON, ie. "{\"Content-Type\": \"application/json\"}"
body (optional) String Body content to send along with the request. If JSON, make sure to set a Content-Type header and stringify the body JSON.
retryable (optional, default true) Boolean Whether the Job should be retried if it fails. If so, the Job is tried again on a backoff schedule of N ** 4 seconds, where N is the number of previous attempts. Maximum of 24 retries. If the Job is recurring then retrying will follow this schedule, otherwise the next run of a failed Job will occur on the regular schedule.
runAt (required) ISO8601 Timestamp An ISO8601 timestamp of when the Job should run. For recurring Jobs, this is the time of the first run. Ex: 2020-08-22T12:34:56Z
runEvery (optional) ISO8601 Duration An ISO8601 duration of the recurring schedule for the Job. Ex: P1D would run once per day, starting at the runAt time. If null then the Job will only run once at the runAt time.

updateJob mutation

Updates a Job. Any existing Runners will be canceled and re-scheduled with the new runAt and runEvery arguments.

Note that you cannot change the name of a Job—updating a Job first looks up the Job by the provided name argument and that's the one that is updated. The equivalent of renaming a Job would be to to delete the existing one and create a new one with the new name.

Arguments

Same as createJob attributes except that all attributes are optional except name.

createOrUpdateJob mutation

If a Job is found with the provided name it is updated with the new values, otherwise a Job is created with that name.

Note that you cannot change the application that a job is tied to. If you provide the applicationName attribute, it will only be used to lookup an existing Job.

Arguments

Same as createJob attributes.

deleteJob mutation

Deletes a Job and any pending Runners. Note that this also removes any JobResult history.

Arguments

name (required) String Name of the Job

JobResults

JobResults are the are the record of what happened when a Job was run. JobResults have their own endpoint, as documented here, but can also be returned as a sub-type of Jobs themselves.

Fields

status Integer The HTTP status code in the response
headers String Any headers returned with the response
body String Any body in the response
runAt ISO8601 Timestamp An ISO8601 timestamp of when the Job was run which created this JobResult. Note that due to Runner backlog this time could be later than the runAt field set on the Job itself.
run Integer A counter that is incremented every time the parent Job was run (either a recurring Job or a single-run Job that has been updated to run multiple times)
duration Integer The number of milliseconds it took to receive the response
createdAt ISO8601 Timestamp n ISO8601 timestamp of when the JobResult was created
updatedAt ISO8601 Timestamp An ISO8601 timestamp of when the JobResult was last updated
job Job Details for the Job this JobResult is attached to.

jobResults query

If given the jobName argument, returns all JobResults for that Job. Otherwise returns all JobResults for the Application used to authenticate.

Arguments

jobName (optional) String Name of a parent Job

Runners

Runners represent the actual processes that execute your Job. You will only see Runner records for Jobs that are actively running, or still scheduled to be run in the future.

There is no stand-alone Runners query—you can only return Runners as a sub-type of a Jobs query.

Fields

priority Integer Number ranging from 0-100 that represents the priority for this Runner, lower numbers have higher priority. Default is 50.
queue String The named queue for this Runner. Default is default
attempts Integer If a Runner fails this field is incremented with every retry.
recurring Boolean Denotes whether this Runner is scheduled to recur (based on whether the Job has a runEvery value set)
running Boolean Denotes whether the Runner is actively executing
runAt ISO8601 Timestamp An ISO8601 timestamp of when the Runner is scheduled to execute
failedAt ISO8601 Timestamp If the Runner has failed (the endpoint returned a status code of >= 400) and the Job is marked as retryable this will be an ISO8601 timestamp of when the Runner last failed
createdAt ISO8601 Timestamp An ISO8601 timestamp of when the Runner was created
updatedAt ISO8601 Timestamp An ISO8601 timestamp of when the Runner was last updated
job Job Detail for the attached Job