Jobs

Overview

The Jobs service provides the APIs needed to run and manage inference jobs that process data through a model. Modzy is able to access data from different sources, such as text, embedded, and data stored in AWS S3 buckets.

Also, this service monitors active jobs and accesses the job history. To see job details, call the API using the same key that submitted the job. The job history route supports pagination.

A job can process multiple items containing data. To run a job, declare a reference input item name and then include the input name the model requires. The reference name is useful to identify the item’s results. Add the data under the model’s input name.

Once submitted, the API returns the job identifier and additional job metadata. Jobs are processed asynchronously according to priority and resource requirements. To check the status call the job details route. Jobs start off as “Submitted” and move to “In Progress” when they begin to run. Once finished, the status is set as “Completed” or “Error”. If a user cancels the job before it finishes, the status is set as “Canceled”.

To retrieve results call the get results route with the job identifier. Results are keyed on the user’s input item names provided upon job submittal. Each model has its own result MIME type, found in the model’s details.

The jobs object

{
    "jobIdentifier": "...",
    "submittedBy": "...",
    "accountIdentifier": "...",
    "model": {},
    "status": "...",
    "createdAt": "...",
    "updatedAt": "...",
    "submittedAt": "...",
    "total": 1,
    "pending": 1,
    "completed": 0,
    "failed": 0,
    "elapsedTime": 12345,
    "queueTime": 12345,
    "timeout": 99999,
    "user": {},
    "jobInputs": [],
    "inputByteAmount": 12345,
    "imageClassificationModel": true
}

Parameter	Type	Description
jobIdentifier	string	The job’s identifier.
submittedBy	string	The API key that submitted the job.
accountIdentifier	string	Identifier linked to the account that requested the job.
model	object	An object that contains the model’s parameters. It can be used as a filter.
status	string	Status of the jobs to be fetched. Defaults to all. It accepts all, timedout, pending, or terminated.
createdAt	string	Time that the job was created in ISO8601 (YYYY-MM-DDThh:mm:ss.sTZD) format.
updatedAt	string	Time that the job status was updated in ISO8601 (YYYY-MM-DDThh:mm:ss.sTZD) format.
submittedAt	string	Time that the job was submitted in ISO8601 (YYYY-MM-DDThh:mm:ss.sTZD) format.
total	number	Amount of items submitted to the job.
pending	number	Amount of items in the item queue, not yet processed by the job.
completed	number	Amount of items processed by the job.
failed	number	Amount of items that the job couldn’t process.
queueTime	number	Time between the job is first submitted and it starts to run the first input in milliseconds.
elapsedTime	number	Time between the job starts to run until it is completed in milliseconds.
timeout	number	Contains a timeout in milliseconds for the job’s status to transition to TIMEDOUT. If it’s not set, jobs don’t timeout.
explain	boolean	Sets the explainability feature when a model offers the option.
user	object	An object that contains the user’s parameters.
jobInputs	array	An array that contains the input objects.
inputByteAmount	number	The job’s total input weight in bytes.
imageClassificationModel	boolean	A flag for image classification models. If true, it creates lightweight samples for the images.

Inputs

The input object holds the input items sent to the model to be processed. Most models only require one input to run successfully but some require more. Input object parameters change based on how the data is stored.

Text inputs

The inputs object - text

{
  "input": {
    "type": "text",
    "sources": {
      "my-input-reference-name-1": {
        "model-x-input-name": "A string to run."
      },
      "my-input-reference-name-2": {
        "model-x-input-name": "Another string to run."
      }
    }
  }
}

Parameter	Type	Description
type	string	The input type to be processed. Use text.
sources	object	Contains all the input item objects to be processed.

The sources object

{
  "my-input-reference-name-1": {}
}

Parameter	Type	Description
input_item_name	object	Contains the input to be processed by the model and defines its name.

The input name object

"model-x-input-name": "A string to run."

Parameter	Type	Description
input	string	A string to be processed. The input name needs to match the model’s input name.

Embedded inputs

The inputs object - embedded

{
  "input": {
    "type": "embedded",
    "sources": {
      "my-image": {
        "image": "data:image/jpeg;base64,/.../2Q=="
      }
    }
  }
}

Parameter	Type	Description
type	string	The input type to be processed. Use embedded.
sources	object	Contains all the input item objects to be processed.

The sources object

{
  "my-input-reference-name-1": {}
}

Parameter	Type	Description
input_item_name	object	Contains the input to be processed by the model and defines its name.

The input item name object

{
  "model-x-input-name": "A string to run."
}

Parameter	Type	Description
input	string	A base64 string to be processed. The input name needs to match the model’s input name.

AWS S3 inputs

The inputs object - aws-s3 / aws-s3-folder

{
  "input": {
    "type": "aws-s3",
    "accessKeyID": "...",
    "secretAccessKey": "...",
    "region": "...",
    "sources": {
      "my-input-reference-name-1": {
          "model-x-input-name": {
            "bucket": "...",
            "key": "..."
          }
      }
    }
  }
}

Parameter	Type	Description
type	string	The input type to be processed. Use `aws-s3` to run a single item or `aws-s3-folder` to run all the items in a folder.
accessKeyID	string	The access key ID provided by AWS.
secretAccessKey	string	The secret access key provided by AWS.
region	string	Name of the geographical area where the input item is stored by AWS.
sources	object	Contains all the input item objects to be processed.

The sources object

{
  "my-input-reference-name-1": {}
 }

Parameter	Type	Description
input_item_name	object	Contains the input to be processed by the model and defines its name.

The input item name object

"model-x-input-name": {
  "bucket": "...",
  "key": "..."
}

Parameter	Type	Description
input	object	An AWS bucket URL and the AWS key. The input name needs to match the model’s input name. Add one per bucket. The key may be a directory or a file.

JDBC inputs

The inputs object - jdbc

{
  "input": {
    "type": "jdbc",
    "url": "...",
    "username": "...",
    "password": "...",
    "driver": "...",
    "query":"..."
  }
}

type	string	The input type to be processed. Use jdbc.
url	string	The URL to connect to the database.
username	string	The username to access the database.
password	string	The password to access the database.
driver	string	The JDBC driver to connect to the database.
query	string	The SQL query to use to get the input item.