Repeater.dev Docs: Home

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.

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.

Authorization: Bearer 8edd2e13df6b840d23b47b0af177a62a

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 8edd2e13df6b840d23b47b0af177a62a" \
--data '{ "query": "{ jobs { name } }" }' \
https://api.repeater.dev/graphql

const repeater = new Repeater('8edd2e13df6b840d23b47b0af177a62a')

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

query {
  jobs {
    name
    application {
      name
      token
    }
  }
}

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.

query {
  jobs {
    name
    enabled
    endpoint
    verb
    headers
    body
    retryable
    runAt
    runEvery
    createdAt
    updatedAt
    lastRunAt
    nextRunAt
  }
}

const jobs = await repeater.jobs()

job query

Returns details for the given Job name.

Arguments

name	(required) `String` Name of the Job

query {
  job(name: "test-job-1") {
    name
    endpoint
  }
}

const job = await repeater.job('test-job-1')

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.

mutation {
  createJob(
    name: "test-job-1"
    endpoint: "https://myapp.com/api/sendEmail"
    verb: "post"
    runAt: "2020-07-24T22:00:00Z"
    headers: "{\"Content-Type\":\"application/json\"}"
    body: "{\"foo\":\"bar\"}"
  ) {
    name
  }
}

const job = await repeater.enqueue({
  name: "test-job-1"
  endpoint: "https://myapp.com/api/sendEmail"
  verb: "post"
  runAt: new Date,
  headers: { 'Content-Type': 'application/json' }
  json: { foo: 'bar' }
})

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.

mutation {
  updateJob(
    name: "test-job-1"
    verb: "get"
  ) {
    name
  }
}

const job = await repeater.job('test-job-1')
await job.update({
  verb: "get"
})

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.

mutation {
  createOrUpdateJob(
    name: "test-job-1"
    endpoint: "https://myapp.com/api/sendEmail"
    verb: "post"
    runAt: "2020-07-24T22:00:00Z"
    headers: "{\"Content-Type\": \"application/json\"}"
    body: "{\"foo\":\"bar\"}"
  ) {
    name
  }
}

const job = await repeater.enqueueOrUpdate({
  name: "test-job-1"
  endpoint: "https://myapp.com/api/sendEmail"
  verb: "post"
  runAt: new Date,
  headers: { 'Content-Type': 'application/json' }
  json: { foo: 'bar' }
})

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

mutation {
  deleteJob(name: "test-job-1") {
    name
  }
}

const job = await repeater.job('test-job-1')
await job.delete()

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

query {
  jobResults(jobName: "test-job-1") {
    status
    headers
    body
    runAt
    run
    duration
    createdAt
    updatedAt
  }
}

const job = await repeater.job('test-job-1')
const results = await job.results()

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

query {
  jobs {
    name
    runners {
      priority
      queue
      attempts
      recurring
      running
      runAt
      failedAt
      createdAt
      updatedAt
    }
  }
}