Overview

Cron To Go REST API conforms to the design principles of Representational State Transfer (REST). To get a running start with the API, we recommend using the curl command-line utility.

All API calls start with: https://api.crontogo.com/organizations/${ORGANIZATION_ID}

The organization ID identifies the Cron To Go instance. The organization ID is exposed to your Heroku app in the CRONTOGO_ORGANIZATION_ID environment variable. You can also copy it from your browser’s address bar after you’ve logged in to Cron To Go.

All API access is provided over HTTPS, and all data is sent and received in the JSON format. Make sure to add the Content-type: application/json header when passing argument data through in an API call.

All API calls are authenticated using an API key passed in the Authorization header as such:
Authorization: Bearer ${CRONTOGO_API_KEY}

The API Key is exposed to Heroku applications in the CRONTOGO_API_KEY environment variable.

In the following documentation, we’ll assume that the following variables have been set:

CRONTOGO_API_KEY=<CronToGo API Key>
ORGANIZATION_ID=<Organization ID>
JOB_ID=<Job ID>

API Reference

List Jobs

Get a list of all jobs.

GET https://api.crontogo.com/organizations/$ORGANIZATION_ID/jobs

Example:

curl --request GET \
  --url https://api.crontogo.com/organizations/$ORGANIZATION_ID/jobs \
  -H "Authorization: Bearer ${CRONTOGO_API_KEY}" \
  -H "Content-type: application/json"

Example output:

Status: 200 OK
[
    {
        "Alias": "Ping website",
        "CreatedAt": 1561888254653,
        "Id": "c531c2d4-9148-48ae-8639-0ab424b3e88a",
        "JobExecutionsCount": 13393,
        "LastAttempt": {
            "CreatedAt": 1615825235358,
            "Id": "3fa80da0-1bfe-40ed-992c-796177d2a148",
            "Response": {
                "Body": "{\"attach_url\":null,\"command\":\"curl -s -w 'URL: %{url_effective} Total time: %{time_total}' -o /dev/null https://myamazingapp.com\",\"created_at\":\"2021-03-15T16:20:35Z\",\"id\":\"3fa80da0-1bfe-40ed-992c-796177d2a148\",\"name\":\"crontogo-c531c2d4-9148-48ae-8639-0ab424b3e88a.6419\",\"app\":{\"id\":\"29b48ba4-f228-45e1-99f3-46383763872e\",\"name\":\"c2g-demo\"},\"release\":{\"id\":\"3a2c9ba3-2507-4960-b1f6-6eee3126f189\",\"version\":306},\"size\":\"Hobby\",\"state\":\"starting\",\"type\":\"crontogo-c531c2d4-9148-48ae-8639-0ab424b3e88a\",\"updated_at\":\"2021-03-15T16:20:35Z\"}",
                "Headers": {},
                "Status": 201,
                "StatusText": "Created"
            },
            "State": "running",
            "StatusCode": 201
        },
        "OrganizationId": "120ffd28-f115-7ce2-abc4-1e168c57c88a",
        "Retries": 0,
        "ScheduleExpression": "*/5 * * * *",
        "ScheduleType": "cron",
        "State": "enabled",
        "Target": {
            "AppId": "29b48ba4-f228-45e1-99f3-46383763872e",
            "Command": "curl -s -w 'URL: %{url_effective} Total time: %{time_total}' -o /dev/null https://myamazingapp.com",
            "Size": "Hobby",
            "TimeToLive": 1800,
            "Type": "dyno"
        },
        "Timezone": "UTC",
        "UpdatedAt": 1615825236023
    }
]

Create Job

Create a new job.

POST https://api.crontogo.com/organizations/$ORGANIZATION_ID/jobs

Parameters:

Name Type Description
Alias string Name for the job
Retries int Number of retries. A job is only retried if Heroku APIs return a bad response or timeout (i.e. not when an application error occurs)
ScheduleExpression string Cron expression
ScheduleType string Always cron
Target.Type string Always dyno
Target.Size string Dyno size (see [ref](https://devcenter.heroku.com/articles/dyno-types?utm_source=crazyantlabs&utm_medium=blog))
Target.Command string Command to execute
Target.TimeToLive int Number of seconds after which the one-off dyno will be killed
State string enabled or paused

Example call:

curl --request POST \
  --url https://api.crontogo.com/organizations/$ORGANIZATION_ID/jobs \
  -H "Authorization: Bearer ${CRONTOGO_API_KEY}" \
  -H "Content-type: application/json" \
  --data '{
    "Alias": "Test",
    "Retries": 2,
    "ScheduleExpression": "*/1 * * * *",
    "ScheduleType": "cron",
    "Target": {
      "Type": "dyno",
      "Size": "Hobby",
      "Command": "echo Hello World",
      "TimeToLive": 1800
    },
    "State": "enabled"
  }'

Example output:

Status: 201 Created
{
    "Alias": "Test",
    "CreatedAt": 1616053604466,
    "Id": "ededf71f-a1cd-477e-b78c-350b691bbfdb",
    "LastAttempt": null,
    "OrganizationId": "120ffd28-f115-7ce2-abc4-1e168c57c88a",
    "Retries": 2,
    "ScheduleExpression": "*/1 * * * *",
    "ScheduleType": "cron",
    "State": "enabled",
    "Target": {
        "AppId": "29b48ba4-f228-45e1-99f3-46383763872e",
        "Command": "echo Hello World",
        "Size": "Hobby",
        "TimeToLive": 1800,
        "Type": "dyno"
    },
    "Timezone": "UTC",
    "UpdatedAt": 1616053604466
}

Update job

Update an existing job. In the argument JSON, only pass the keys necessary to update.

PATCH https://api.crontogo.com/organizations/$ORGANIZATION_ID/jobs/$JOB_ID

Parameters - see (Create job)[#createjob] parameters

Example call:

curl --request PATCH \
  --url https://api.crontogo.com/organizations/$ORGANIZATION_ID/jobs/$JOB_ID \
  -H "Authorization: Bearer ${CRONTOGO_API_KEY}" \
  -H "Content-type: application/json" \
  --data '{
    "Retries": 5
  }'

Example response:

200 OK
{
    "Alias": "Test",
    "CreatedAt": 1616053604466,
    "Id": "ededf71f-a1cd-477e-b78c-350b691bbfdb",
    "LastAttempt": {
        "CreatedAt": 1616053921010,
        "Id": "5c77e1ee-30e2-4d60-9bf4-f37afdc8353f",
        "Response": {
            "Body": "{\"attach_url\":null,\"command\":\"echo Hello World\",\"created_at\":\"2021-03-18T07:52:01Z\",\"id\":\"5c77e1ee-30e2-4d60-9bf4-f37afdc8353f\",\"name\":\"crontogo-ededf71f-a1cd-477e-b78c-350b691bbfdb.6607\",\"app\":{\"id\":\"29b48ba4-f228-45e1-99f3-46383763872e\",\"name\":\"c2g-demo\"},\"release\":{\"id\":\"98a09a01-1085-428c-8313-0c0e350b8ceb\",\"version\":307},\"size\":\"Hobby\",\"state\":\"starting\",\"type\":\"crontogo-ededf71f-a1cd-477e-b78c-350b691bbfdb\",\"updated_at\":\"2021-03-18T07:52:01Z\"}",
            "Headers": {},
            "Status": 201,
            "StatusText": "Created"
        },
        "State": "running",
        "StatusCode": 201
    },
    "OrganizationId": "120ffd28-f115-7ce2-abc4-1e168c57c88a",
    "Retries": 5,
    "ScheduleExpression": "*/1 * * * *",
    "ScheduleType": "cron",
    "State": "enabled",
    "Target": {
        "AppId": "29b48ba4-f228-45e1-99f3-46383763872e",
        "Command": "echo Hello World",
        "Size": "Hobby",
        "TimeToLive": 1800,
        "Type": "dyno"
    },
    "Timezone": "UTC",
    "UpdatedAt": 1616053927264
}

Delete job

Delete an existing job.

DELETE https://api.crontogo.com/organizations/$ORGANIZATION_ID/jobs/$JOB_ID

Example call:

curl --request DELETE \
  --url https://api.crontogo.com/organizations/$ORGANIZATION_ID/jobs/$JOB_ID \
  -H "Authorization: Bearer ${CRONTOGO_API_KEY}" \
  -H "Content-type: application/json" \

Example response:

200 OK
{
    "Alias": "Test",
    "CreatedAt": 1616053604466,
    "Id": "ededf71f-a1cd-477e-b78c-350b691bbfdb",
    "LastAttempt": {
        "CreatedAt": 1616053921010,
        "Id": "5c77e1ee-30e2-4d60-9bf4-f37afdc8353f",
        "Response": {
            "Body": "{\"attach_url\":null,\"command\":\"echo Hello World\",\"created_at\":\"2021-03-18T07:52:01Z\",\"id\":\"5c77e1ee-30e2-4d60-9bf4-f37afdc8353f\",\"name\":\"crontogo-ededf71f-a1cd-477e-b78c-350b691bbfdb.6607\",\"app\":{\"id\":\"29b48ba4-f228-45e1-99f3-46383763872e\",\"name\":\"c2g-demo\"},\"release\":{\"id\":\"98a09a01-1085-428c-8313-0c0e350b8ceb\",\"version\":307},\"size\":\"Hobby\",\"state\":\"starting\",\"type\":\"crontogo-ededf71f-a1cd-477e-b78c-350b691bbfdb\",\"updated_at\":\"2021-03-18T07:52:01Z\"}",
            "Headers": {},
            "Status": 201,
            "StatusText": "Created"
        },
        "State": "running",
        "StatusCode": 201
    },
    "OrganizationId": "120ffd28-f115-7ce2-abc4-1e168c57c88a",
    "Retries": 5,
    "ScheduleExpression": "*/1 * * * *",
    "ScheduleType": "cron",
    "State": "enabled",
    "Target": {
        "AppId": "29b48ba4-f228-45e1-99f3-46383763872e",
        "Command": "echo Hello World",
        "Size": "Hobby",
        "TimeToLive": 1800,
        "Type": "dyno"
    },
    "Timezone": "UTC",
    "UpdatedAt": 1616053927264
}

Get job execution history

Get all execution history for a specific job.

GET https://api.crontogo.com/organizations/$ORGANIZATION_ID/jobs/$JOB_ID/executions

Example call:

curl --request GET \
  --url https://api.crontogo.com/organizations/$ORGANIZATION_ID/jobs/$JOB_ID/executions \
  -H "Authorization: Bearer ${CRONTOGO_API_KEY}" \
  -H "Content-type: application/json"

Example response:

200 OK
[
    {
        "AttemptsCount": 1,
        "CreatedAt": 1616054410955,
        "ExpiresAt": 1616140811,
        "Id": "d12ae389-edb5-49c3-9823-0c36c845edb4",
        "JobId": "ededf71f-a1cd-477e-b78c-350b691bbfdb",
        "LastAttempt": {
            "CreatedAt": 1616054410704,
            "ExitStatus": 0,
            "Id": "2a8c31de-62b9-4dce-9be9-76df5adc5476",
            "Response": {
                "Body": "{\"attach_url\":null,\"command\":\"echo Hello World\",\"created_at\":\"2021-03-18T08:00:10Z\",\"id\":\"2a8c31de-62b9-4dce-9be9-76df5adc5476\",\"name\":\"crontogo-ededf71f-a1cd-477e-b78c-350b691bbfdb.4565\",\"app\":{\"id\":\"29b48ba4-f228-45e1-99f3-46383763872e\",\"name\":\"x2g-automation\"},\"release\":{\"id\":\"98a09a01-1085-428c-8313-0c0e350b8ceb\",\"version\":307},\"size\":\"Hobby\",\"state\":\"starting\",\"type\":\"crontogo-ededf71f-a1cd-477e-b78c-350b691bbfdb\",\"updated_at\":\"2021-03-18T08:00:10Z\"}",
                "Headers": {},
                "Status": 201,
                "StatusText": "Created"
            },
            "State": "succeeded",
            "StatusCode": 201
        },
        "NextAttemptAt": null,
        "OrganizationId": "120ffd28-f115-7ce2-abc4-1e168c57c88a",
        "State": "succeeded",
        "Target": {
            "AppId": "29b48ba4-f228-45e1-99f3-46383763872e",
            "Command": "echo Hello World",
            "Size": "Hobby",
            "TimeToLive": 1800,
            "Type": "dyno"
        },
        "TriggerType": "schedule",
        "UpdatedAt": 1616054429860
    }
]

Trigger job execution

Making this call will trigger immediate job execution, regardless of whether the job is already running or not.

POST https://api.crontogo.com/organizations/$ORGANIZATION_ID/jobs/$JOB_ID/executions

Example call:

curl --request POST \
  --url https://api.crontogo.com/organizations/$ORGANIZATION_ID/jobs/$JOB_ID/executions \
  -H "Authorization: Bearer ${CRONTOGO_API_KEY}" \
  -H "Content-type: application/json"

Example response:

201 Created
{}