Skip to main content

View and manage jobs by API

After you create an ingestion job for Imply Polaris, you can get its status, view related metrics, and stop its execution. This topic walks you through the process of viewing job-related details and canceling a job.

For details on starting ingestion jobs, see Create an ingestion job by API.

info

Project-less regional API resources have been deprecated and will be removed by the end of September 2024. See Migrate to project-scoped URL for more information.

Prerequisites​

This topic assumes that you have an API key with the ManageIngestionJobs permission. In the examples below, the key value is stored in the variable named POLARIS_API_KEY. For information about how to obtain an API key and assign permissions, see API key authentication. For more information on permissions, visit Permissions reference.

Get job status​

Use the job status API to get the status of your job. Issue a GET request to the following endpoint. Replace PROJECT_ID with your Polaris project ID and JOB_ID with the ID of your job.

/v1/projects/PROJECT_ID/jobs/JOB_ID/status

If you need to identify your job ID, send a GET request to the Jobs v1 API without specifying a job ID to retrieve information about all jobs. That is, submit a request to the following endpoint:

/v1/projects/PROJECT_ID/jobs

To get additional metadata for the job, such as its health or ingestion specification, submit a GET request to the jobs endpoint with the specific job ID:

/v1/projects/PROJECT_ID/jobs/JOB_ID

Sample request​

The following example shows how to get the status of a job that has job ID efb35e3e-406e-4127-ad2e-280fede4f431:

curl --location --request GET "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/PROJECT_ID/jobs/efb35e3e-406e-4127-ad2e-280fede4f431/status" \
--header "Authorization: Basic $POLARIS_API_KEY" \
--data-raw ''

Sample response​

The following example shows a successful response for a job's progress:

{
  "executionStatus": "idle"
}

Update job status​

Use the job status API to change the execution status of a job.

Note that you can also update a job's status by sending a PUT request to the jobs endpoint. However, we recommending sending a POST request to the job status endpoint, as described in this section.

Stop a job​

To stop a job, issue a POST request to the job status API, and in your request body set desiredExecutionStatus to canceled.

{
  "desiredExecutionStatus": "canceled"
}

For details on stopping jobs, see Manage jobs.

Pause or resume a streaming job​

You can pause and resume streaming ingestion jobs. In your request to the job status API, send the following request body to pause or resume a job, respectively:

Pause a job:

{
  "desiredExecutionStatus": "suspended"
}

Resume a paused job:

{
  "desiredExecutionStatus": "running"
}

Sample request​

The following example shows how to stop a job with the job ID efb35e3e-406e-4127-ad2e-280fede4f431:

curl --location --request PUT "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/PROJECT_ID/jobs/efb35e3e-406e-4127-ad2e-280fede4f431/status" \
--header "Authorization: Basic $POLARIS_API_KEY" \
--header "Content-Type: application/json" \
--data-raw '{
    "desiredExecutionStatus": "canceled"
}'

Sample response​

When you successfully stop a job, the Jobs v1 API returns the 200 OK status code and the details of the job.

View job metrics​

Send a GET request to /v1/projects/PROJECT_ID/jobs/JOB_ID/metrics to view the metrics for a job. Replace JOB_ID with the ID of the job.

The following example shows metrics for an ingestion job in which two rows could not be parsed. By default, Polaris continues to ingest data when it encounters rows it cannot parse. You can specify a threshold for parsing exceptions for a job. The job fails if the number of parsing exceptions exceeds the threshold. Set this limit in maxParseExceptions when creating an ingestion job. You can view parse exception messages in the job logs.

You can also use the UI to monitor the health of your ingestion job. For more information, see Monitor streaming ingestion from a connection.

Sample request​

The following example shows how to view metrics for an ingestion job with the job ID db6a3110-d6c3-4a63-86b2-41d51a65ce11:

curl --location --request GET "https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/PROJECT_ID/jobs/db6a3110-d6c3-4a63-86b2-41d51a65ce11/metrics" \
--header "Authorization: Basic $POLARIS_API_KEY"

Sample response​

The following example shows a successful response for metrics of an ingestion job:

{
    "totals": {
        "numRowsProcessed": 99999,
        "numRowsProcessedWithWarning": 0,
        "numRowsSkippedByFilter": 0,
        "numRowsSkippedByError": 2
    }
}

Learn more​

See the following topics for more information: