Managing jobs in Management API

Managing jobs in Management API#

This article documents how to list current jobs, list past jobs, obtain a status of jobs in progress, and how to stop jobs with the Management API.

Listing jobs#

Listing all jobs in an instance#

Use the API call documented in this section to list all currently running and scheduled jobs (for example, fetch jobs) in a whole instance.

To list all running and scheduled jobs, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/jobs

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/jobs/' \
--header 'Authorization: Token {{KEY}}'

The response to this request includes the state_label parameter with one of the following values assigned:

  • Scheduled

  • Running

  • Success

  • Cancelled

  • Failed

  • Discarded - this status is set in the following cases:

    • If a preceding job failed or was cancelled, the follow up jobs are discarded.

    • If a job does not start running within 2 days of the fetch start, it is discarded.

    • If a job is cancelled manually, it is discarded.

  • Stale - this status is not set currently. Generally, it can be used to label jobs that will not complete due to internal failures and lost or removed tasks.

Listing jobs of datastream#

To list currently running jobs for a datastream, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/jobs/?datastream_id={{DATASTREAM_ID}}/

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request GET 'https://{{INSTANCE}}/api/jobs/?datastream_id={{DATASTREAM_ID}}/' \
--header 'Authorization: Token {{KEY}}'

Listing past jobs within a given date range#

To list past jobs within a given date range, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/jobs/?start=YYYY-MM-DD&end=YYYY-MM-DD

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request GET 'https://{{INSTANCE}}/api/jobs/?start=YYYY-MM-DD&end=YYYY-MM-DD'
             \
--header 'Authorization: Token {{KEY}}'

Listing past jobs within a given time range#

To list past jobs within a more specific time range, you can include a timestamp in your request. To do this, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/jobs/?start=YYYY-MM-DDT00:00:00Z&end=YYYY-MM-DDT00:00:00Z

    For example, to list all jobs on October 31, 2022, use the following date and timestamps:

    start=2022-10-31T00:00:00Z&end=2022-10-31T23:59:59Z

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request GET 'https://{{INSTANCE}}/api/jobs/?start=YYYY-MM-DDT00:00:00Z&end=YYYY-MM-DDT00:00:00Z'
             \
--header 'Authorization: Token {{KEY}}'

Obtaining the status of a job in progress#

To obtain a status of a job in progress, follow these steps:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/jobs/{{JOB_ID}}/imported/

    Find the value of JOB_ID parameter in the response of the API request described in the previous section. In this response, JOB_ID parameter is named as id.

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request GET 'https://{{INSTANCE}}/api/jobs/{{JOB_ID}}/imported/' \
--header 'Authorization: Token {{KEY}}'

Stopping jobs#

To stop a job, list the currently running jobs, and find the JOB_ID of the job to stop. You can only stop jobs in the fetch stage.

To stop a job using JOB_ID, follow these steps:

  1. Create a POST request to the following endpoint:

    https://{{INSTANCE}}/api/jobs/{{JOB_ID}}/stop/

  2. In the HTTP request header, include the parameter Authorization with one of the following values:

    • Token {{KEY}} if you use a key generated with user credentials in Management API.

    • Bearer {{KEY}} if you use a key generated in the Adverity user interface.

  3. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location -g --request POST 'https://{{INSTANCE}}/api/jobs/{{JOB_ID}}/stop/' \
--header 'Authorization: Token {{KEY}}'
Contents