Scheduler API

Use the Scheduler API to manage schedule operations, including creating, viewing, managing, and scheduling jobs.

See Instabase API authorization and response conventions for authorization and response convention details.

Create a scheduled job

Method Syntax
POST URL_BASE/api/v1/scheduler/create_job

Description

Create a scheduled job that will run on a regular interval.

Request body

Parameter Type Description
schedule string A cron expression representing the schedule with which this job can be run. The smallest supported interval is minutes.
name string The name of this scheduled job.
flow_parameters object An object describing the flow triggered when this job runs.
flow_parameters/auth_token string Instabase authentication token. See Creating API access token.
flow_parameters/binary_path string The file path to the flow binary (.iflowbin) file.
flow_parameters/input_dir string The folder containing the data to run the flow on.
flow_parameters/verify_ssl_certificate boolean (Optional) Set to false to skip SSL certificate verification when starting a flow. Defaults to true if not specified.
flow_parameters/settings object (Optional) Settings for the flow that will be triggered. For more information on flow parameters, see the settings parameter in the Run a flow binary API documentation.
flow_parameters/settings/spooled_mode boolean (Optional) Set to true to enable automatic mode (previously called spooled mode). Defaults to false if not specified. See the Automatic mode section below for more information.
flow_parameters/settings/tags array (Optional) A list of tags to apply to flow executions triggered by this job.
flow_parameters/settings/runtime_config object (Optional) Set a runtime configuration for the flow.
flow_parameters/settings/notification_emails string (Optional) A comma-separated list of email addresses to send notifications to.
flow_parameters/settings/webhook_config object (Optional) Configure a webhook URL that will be notified on flow completion.
flow_parameters/settings/webhook_config/url string The webhook URL to which a notification event will be sent when the run is completed.
flow_parameters/settings/webhook_config/headers object (Optional) HTTP headers to use when triggering the webhook.

Acceptable values for the schedule parameter:

  • @hourly

  • @daily

  • @weekly

  • @monthly

  • @yearly

  • any valid cron expression, see below

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
│ │ │ │ │
* * * * *

Automatic mode

When automatic mode is enabled, scheduler jobs will automatically start a new Flow job for every file that is added to the input directory. When automatic mode is enabled (spooled_mode is set to true) the schedule argument is not used.

Response schema

Key Type Description Value
status string Whether the API call succeeded. OK or ERROR
job_id string The ID of the new scheduler job. A scheduler job ID.

Examples

Request

Example (Python):

url = url_base + '/api/v1/scheduler/create_job'

args = {
    "schedule": "@daily",
    "name": "Daily Job",
    "flow_parameters": {
        "auth_token": "<oauth token>",
        "binary_path": "admin/repo/fs/Instabase Drive/files/flow/flow.ibflowbin",
        "input_dir": "admin/repo/fs/Instabase Drive/files/flow/input",
        "verify_ssl_certificate": True,
        "settings": {
            "tags": ["tag1"],
            "runtime_config": {},
            "notification_emails": "example@email.com",
            "webhook_config": {
                "url": "https://example.com/webhook",
                "headers": {
                    "Authorization": "Bearer 12345"
                }
            }
        }
    }
}
json_data = json.dumps(args)

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

r = requests.post(url, data=json_data, headers=headers)
resp_data = json.loads(r.content)

Response

The response body is a JSON object.

If successful:

HTTP STATUS CODE 200

# body
{
    "status": "OK",
    “job_id: "6bc58441-1f60-4265-99f1-881c90ac65df"
}

List scheduled jobs

Method Syntax
GET URL_BASE/api/v1/scheduler/list_jobs

Description

Get a list of scheduler jobs.

Request body

Parameter Type Description Value
job_id string (Optional) A scheduler job ID to retrieve. If this is passed, the response contains only details for that single job.
username string (Optional) If passed, fetch only jobs owned by the given username. A valid instabase username or ‘*’ to list jobs of all users

Response schema

Key Type Description Value
status string Whether the API call succeeded. OK or ERROR
jobs array An array of scheduler job objects.
jobs/job_id string The job ID for this scheduler job.
jobs/name string The name of this job.
jobs/username string The username that owns this scheduler job.
jobs/status string Whether this job is enabled. ENABLED or DISABLED
jobs/created_on_ns string The timestamp of when this job was created.
jobs/job_parameters object The object that describes the Flow that this job is triggering. See the flow_parameters argument in create a scheduled job.
jobs/results array An array of results generated from this job’s Flow executions. This shows the results for the last 10 executions.
jobs/results/timeInNS string The timestamp of when this job execution finished.
jobs/results/status string The status returned from this job execution. OK or ERROR
jobs/results/http_result object The HTTP response from the Run Binary API invocation that this job executed.
jobs/results/http_result/status string The HTTP status returned from the Run Binary API invocation. An HTTP status code, formatted as a string.
jobs/results/http_result/headers array An array of headers in the HTTP response for this Run Binary API invocation.
jobs/results/http_result/headers/key string The name of this HTTP header.
jobs/results/http_result/headers/value string The value of this HTTP header.
jobs/results/http_result/response string The body of the HTTP response, which includes the flow job ID and other fields. For more information, see the Run a flow binary API documentation.

Examples

Request

Example (Python):

url = url_base + '/api/v1/scheduler/list_jobs'

args = {
    "job_id": "07a3e5c1-1b4f-4852-9cd6-1a072fc8ab31",
    "username": "admin"
}

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

r = requests.get(url, params = args, headers=headers)
resp_data = json.loads(r.content)

Response

The response body is a JSON object.

If successful:

HTTP STATUS CODE 200

# body
{
    "status": "OK",
    "jobs": [{
        "job_id": "07a3e5c1-1b4f-4852-9cd6-1a072fc8ab31",
        "username": "admin",
        "status": "ENABLED",
        "name": "Daily Job",
        "created_on_ns": "1660310051723648297",
        "job_parameters": {
            "schedule": "@daily",
            "name": "Daily Job",
            "flow_parameters": {
                "auth_token": "<oauth token>",
                "binary_path": "admin/repo/fs/Instabase Drive/files/flow/flow.ibflowbin",
                "input_dir": "admin/repo/fs/Instabase Drive/files/flow/input",
                "verify_ssl_certificate": True,
                "settings": {
                    "tags": ["tag1"],
                    "runtime_config": {},
                    "notification_emails": "example@email.com",
                    "webhook_config": {
                        "url": "https://example.com/webhook",
                        "headers": {
                            "Authorization": "Bearer 12345"
                        }
                    }
                }
            }
        },
        "results": [{
            "timeInNS": "1665446403651243100",
            "status": "OK",
            "http_result": {
                "status": "200",
                "headers": [{
                    "key": "Content-Type",
                    "value": "application/json"
                }],
                "response": "{\"status\": \"OK\", \"data\": {\"job_id\": \"462eeed8-b051-45c8-8813-8a96d55991f9\", \"output_folder\": \"admin/repo/fs/Instabase Drive/files/flow/out\"}}"
            }
        }]
    }]
}

Delete a scheduled job

Method Syntax
POST URL_BASE/api/v1/scheduler/delete_job

Description

Delete a scheduler job.

Request body

Parameter Type Description
delete_all boolean (Optional) If true, delete all scheduler jobs. Defaults to false.
job_id string (Optional) If passed, the scheduler job ID to delete.

At least one of delete_all or job_id must be specified.

Response schema

Key Type Description Value
status string Whether the API call succeeded. OK or ERROR
deleted_jobs string The scheduler job ID that was deleted. A scheduler job ID.

Examples

Request

Example (Python):

url = url_base + '/api/v1/scheduler/delete_job'

args = {
    "job_id": "07a3e5c1-1b4f-4852-9cd6-1a072fc8ab31"
}
json_data = json.dumps(args)

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

r = requests.post(url, data=json_data, headers=headers)
resp_data = json.loads(r.content)

Response

The response body is a JSON object.

If successful:

HTTP STATUS CODE 200

# body
{
    "status": "OK",
    "deleted_jobs": "07a3e5c1-1b4f-4852-9cd6-1a072fc8ab31"
}

Enable a scheduled job

Method Syntax
POST URL_BASE/api/v1/scheduler/enable_job

Description

Enable a scheduler job.

Request body

Parameter Type Description
job_id string The scheduler job ID to enable.

Response schema

Key Type Description Value
status string Whether the API call succeeded. OK or ERROR
enabled_jobs string The scheduler job ID that was enabled. A scheduler job ID.

Examples

Request

Example (Python):

url = url_base + '/api/v1/scheduler/enable_job'

args = {
    "job_id": "07a3e5c1-1b4f-4852-9cd6-1a072fc8ab31"
}
json_data = json.dumps(args)

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

r = requests.post(url, data=json_data, headers=headers)
resp_data = json.loads(r.content)

Response

The response body is a JSON object.

If successful:

HTTP STATUS CODE 200

# body
{
    "status": "OK",
    "enabled_jobs": "07a3e5c1-1b4f-4852-9cd6-1a072fc8ab31"
}

Disable a scheduled job

Method Syntax
POST URL_BASE/api/v1/scheduler/disable_job

Description

Disable a scheduler job.

Request body

Parameter Type Description
job_id string The scheduler job ID to enable.

Response schema

Key Type Description Value
status string Whether the API call succeeded. OK or ERROR
disabled_jobs string The scheduler job ID that was disabled. A scheduler job ID.

Examples

Request

Example (Python):

url = url_base + '/api/v1/scheduler/disable_job'

args = {
    "job_id": "07a3e5c1-1b4f-4852-9cd6-1a072fc8ab31"
}
json_data = json.dumps(args)

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

r = requests.post(url, data=json_data, headers=headers)
resp_data = json.loads(r.content)

Response

The response body is a JSON object.

If successful:

HTTP STATUS CODE 200

# body
{
    "status": "OK",
    "disabled_jobs": "07a3e5c1-1b4f-4852-9cd6-1a072fc8ab31"
}

Manually trigger a scheduler

Method Syntax
POST URL_BASE/api/v1/scheduler/trigger_job

Description

Manually trigger a scheduler job.

Request body

Parameter Type Description
job_id string The scheduler job ID to enable.

Response schema

Key Type Description Value
status string Whether the API call succeeded. OK or ERROR
triggered_job string The scheduler job ID that was triggered. A scheduler job ID.

Examples

Request

Example (Python):

url = url_base + '/api/v1/scheduler/trigger_job'

args = {
    "job_id": "07a3e5c1-1b4f-4852-9cd6-1a072fc8ab31"
}
json_data = json.dumps(args)

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

r = requests.post(url, data=json_data, headers=headers)
resp_data = json.loads(r.content)

Response

The response body is a JSON object.

If successful:

HTTP STATUS CODE 200

# body
{
    "status": "OK",
    "triggered_job": "07a3e5c1-1b4f-4852-9cd6-1a072fc8ab31"
}