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:
- Create an Application
- Create one or more Jobs to be run in the future
- 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.
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 |
String Used 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
|