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
{}