Jobs#

A job represents the analysis of a sample and is used to track its progress. On its own it holds no analysis results or verdicts, but contains information such as when an analysis job was started and completed, and whether it failed or not. A job also contains one or more job tasks. The jobs API is intended to be used by the external system managing the analysis itself. A job can not be created manually via any API endpoint. It is automatically created by the Sample service based on incoming submissions.

Fetching jobs#

The role SAMPLEDB-VIEWER or higher is required to be able to fetch or list jobs.

List#

To list analysis jobs, the jobs endpoint can be used with a GET operation. The response body will be in JSON format, and contain a list of objects containing information about the job.

curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/sampledb/v2/job

For more detailed information on what the response model looks like, you can check out the Swagger API documentation.

Fetch#

To fetch a single instance of an analysis job, the fetch job endpoint can be used with a GET operation. The response body will be in JSON format, and contain all information about the job.

curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/sampledb/v2/job/<job id>

For more detailed information on what the response model looks like, you can check out the Swagger API documentation.

Searching for jobs#

To perform an advanced search the job search endpoint can be used with a POST operation along with a JSON body making up the search criteria. The response body will be JSON formatted and contain a list of job objects.

The example below will search for jobs that were timed out in the last week.

curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/sampledb/v2/job/search -d '{
	"state": [
		"timeout"
	],
	"startTimestamp": "now - 1 week",
	"endTimestamp": "now",
	"timeFieldStrategy": [
		"enqueuedTimestamp",
		"startTimestamp",
		"endTimestamp"
	],
	"timeMatchStrategy": "any"
}'

For more detailed information on what the response model looks like, you can check out the Swagger API documentation.

The table below contains a list of valid query parameters and how they work.

Query parameter

Default value

Description

limit

25

Limit the number of search results. Can be anywhere in the range of 0 to 10,000.

offset

0

Skip the first ‘offset’ number of objects

sortBy

enqueuedTimestamp

Sort the result by the value of certain fields. This parameter may be a list of parameter values. Refer to the Swagger API documentation for a list of possible values

state

Return jobs in the defined states only

sampleSha256

Return jobs for certain samples only

customer

Return jobs for certain customers only

startTimestamp

The start timestamp to search for jobs within a time range

endTimestamp

The end timestamp to search for jobs within a time range

timeFieldStrategy

Which timestamp fields to use when searching within a time range

timeMatchStrategy

Whether all or any of the time fields must fall within the specified time range