v1/jobs

Use the v1/jobs API to list, cancel, or delete jobs in an account.

URI

http://<hostname>/ws/v1/jobs

Formats

Method Formats Description
GET /ws/v1/jobs Get a summary of the jobs API.
GET /ws/v1/jobs/inventory Get a list of all jobs.
GET /ws/v1/jobs/inventory.xml Get a list of all jobs in XML format.
GET /ws/v1/jobs/bulk Retrieve a list of jobs in CSV format.
GET /ws/v1/jobs/{job_id} Retrieve a job
PUT /ws/v1/jobs/cancel{job_id} Cancel one or more jobs.
PUT /ws/v1/jobs/inventory/cancel?query=username=’{username}' Cancel one or more jobs for a user.
DELETE /ws/v1/jobs/inventory/{id} Delete a job.
DELETE /ws/v1/jobs/cancel?query=job_type=’{job_type}' Delete one or more jobs by job type.

Parameters

Name Description
orderby Specify any field described in the query parameter syntax. Optionally add ‘asc’ or ‘desc’ to control the sort order. For example, to order with most recently created jobs first, specify orderby=id desc.Note The default sort order is desc (descending).
fields Comma-separated list of fields to return for bulk API
query Specify the jobs query to evaluate. See v1 API Query Language.
cursor
size

Query fields

  • carrier/carrier2—the current provider of the primary or secondary cellular service
  • connection_status—one of ‘connected’ or ‘disconnected’
  • contact—any user contact information
  • description—any description associated with the device
  • firmware_version—the firmware level
  • health_status—one of ’normal’, ‘warning’, ’error’ or ‘unknown’
  • id—the device ID
  • ip—the last known IP address of the device
  • last_connect—last connect time of the device
  • last_disconnect—last disconnect time of the device
  • last_update—last update time of the device
  • location—the device location
  • mac - the MAC address
  • name - the device name
  • network/network2—the current network (for example LTE) of the primary or secondary cellular service
  • notes—device notes, also sometimes referred to as user meta data)
  • public_ip—the last known global IP address of the device
  • restricted_status—one of ‘unrestricted’, ‘restricted’, ‘disabled’, ‘untrusted’
  • serial_number—the device serial number
  • signal_percent/signal_percent2—the percent of signal strength from 0 to 100 primary or secondary cellular service
  • signal_quality/signal_quality2—the signal quality of the primary or secondary cellular service
  • signal_strength/signal_strength2—the signal strength of the primary or secondary cellular service
  • type—the device type
  • vendor_id—the vendor ID value of the device

Query operators

  • =, <>—Equality comparisons, used on any numeric, group, tag, text or enumerated fields
  • <, <=, >, >=—Relative comparisons, used on any numeric or text fields. Not used for group, tag or enumerated fields
  • startsWith, endsWith, contains—Used on any group, tag or text matching fields. Not used for numeric fields

Timestamp field comparisons are not supported.

Query examples

  • Complex queries
query=group startsWith '/NorthWest' and (connection_status = 'disconnected' or signal_percent < 20)

Find any devices in the /Northwest group and any subgroups that are either disconnected or have a low signal strength.

query=tags = 'important' and (health_status = 'error' or health_status = 'warning')

Find any devices that have the ‘important’ tag and are in an error or warning health status.

  • Group queries
query=group = '/test'

Query full group path, so matches any device in group ‘/test’ and ignores any subgroups.

query=group startsWith 'test/'

Query full group path, so matches any device in the test root group and any subgroups.

query=group startsWith 'test'

Query full group path, so matches any device in any root group whose name starts with ’test’ and all subgroups.

query=group endsWith '/leaf'

Query full group path, so matches any device in any path that ends with the group name ’leaf’.

  • Tag Queries
query=tags = 'sensor'

Matches any device having a tag ‘sensor’.

query=tags <> 'sensor'

Matches any device having no tag ‘sensor’.

query=tags contains 'ns'

Matches any device having any tag containing ’ns’.

query=tags startsWith 'sens'

Matches any device having any tag that starts with ‘sens’.

query=tags endsWith 'or'

Matches any device having any tag that ends with ‘or’.