Overview

Version information

Version : 2.9

URI scheme

Host : api.<server_domain>
BasePath : /v2.9
Schemes : HTTPS

Tags

  • auth : This service provides authentication management and authorization validation for the entire system.

  • debug : debugging utilities

  • events : Provides an API for running tasks to report events collected by the system.

  • models : This service provides a management interface for models (results of training tasks) stored in the system.

  • organization : This service provides organization level operations

  • projects : Provides support for defining Projects containing Tasks, Models and Dataset Versions.

  • queues : Provides a management API for queues of tasks waiting to be executed by workers deployed anywhere (see Workers Service).

  • server : server utilities

  • tasks : Provides a management API for tasks in the system.

  • users : This service provides a management interface to users information and new users login restrictions.

  • workers : Provides an API for worker machines, allowing workers to report status and get tasks for execution

Produces

  • application/json

Protocol and Security

The API exclusively supports the HTTPS protocol in order to provide a high level of security. The API supports both GET and POST methods with no implementation difference.

Furthermore, all endpoints require authorization in order to protect user and company resources.

Authentication

All endpoints in this API require authentication to be performed. In order to authenticate, authorization credentials must be provided when making API calls.

Obtaining authorization credentials

The system supports two means of authorization: credentials and bearer tokens. Registered users can obtain credentials in the form of key/secret using the Allegro Trains Web Platform. Using these credentials, the Authentication Service can then be used to generate bearer tokens required for making authorized API calls.

Making an authorized API call

The authorization data used for authenticating each request should be present in the message headers (see Authorization).

Versioning

When sending a request to a specific API endpoint, the API version number must be specified.

https://api.<server_domain>/v<version-number>/<service-name>.<action>

For example, to access the get_by_id action of the tasks service in API version 2.9, the following URL should be used:

https://api.<server_domain>/v2.9/tasks.get_by_id

Note that there is no default version.

Message Headers

Authorization

Header Name Contents

Authorization

Authorization data, in the format of <auth-type> <auth-data>.

Type Data

Basic

Base64-encoded string, containing user credentials in the following format:

<client-id>:<client-secret>

Bearer

Bearer token generated by the Authentication Service or otherwise provided by the system.

X-Trains-Worker

Worker machine name/ID. This is used by the platform when logging API calls.

X-Trains-Client

Trains client name and version.

X-Trains-Impersonate-As

Impersonated user ID. Request this API call to be made under the provided user’s identity and permissions. Can only be requested by users with the admin role.

X-Trains-Act-As

Impersonated user ID. Request this API call to be made under the provided user ID (and his company ID), but with the caller’s role and permissions. Can only be requested by users with the admin role.

Content Type

Content type Description Supported

application/json

Payload is a json-encoded string.

Example
{"task": "4462b0f8-4064-45ec-b604-a574e7ce7179"}

All

application/json-lines

Payload is a string containing json-encoded strings joined with newline characters.

Example
{"task": "4462b0f8-4064-45ec-b604-a574e7ce7179"}\n
{"task": "1542f1c1-3b28-4456-aab9-0d3a0da54eca"}\n
{"task": "eefee921-5858-48d5-8d0e-a92a9a91470b"}\n

Partial

Common Elements

Class Types

Affine

bypass, scale, reflect, rotate, shear, reflect-horiz, reflect-vert

Pixel

bypass, blur, noise, recolor

Resources

Auth

This service provides authentication management and authorization validation for the entire system.

Debug

debugging utilities

POST /debug.ping

Description

Ping server

Body parameter
Responses

Events

Provides an API for running tasks to report events collected by the system.

POST /events.add

Description

Adds a single event

Body parameter
Responses

POST /events.add_batch

Description

Adds a batch of events in a single call (json-lines format, stream-friendly)

Body parameter

Json encoded newline-terminated lines, each representing an event in the batch and uses the same parameters used for events.add

Responses

Response 200

Name Schema

added
optional

integer

errors
optional

integer

errors_info
optional

object

POST /events.debug_images

Description

Get the debug image events for the requested amount of iterations per each
task’s metric

Body parameter
Name Description Schema

metrics
required

List metrics for which the envents will be retreived

< events.task_metric > array

iters
optional

Max number of latest iterations for which to return debug images

integer

navigate_earlier
optional

If set then events are retreived from latest iterations to earliest ones.
Otherwise from earliest iterations to the latest. The default is True

boolean

refresh
optional

If set then scroll will be moved to the latest iterations. The default is False

boolean

scroll_id
optional

Scroll ID of previous call (used for getting more results)

string

Responses

Response 200

Name Description Schema

metrics
optional

Debug image events grouped by task metrics and iterations

< object > array

scroll_id
optional

Scroll ID for getting more results

string

POST /events.delete_for_task

Description

Delete all task event. This cannot be undone!

Body parameter
Name Description Schema

task
required

Task ID

string

allow_locked
optional

Allow deleting events even if the task is locked
Default : false

boolean

Responses

Response 200

Name Description Schema

deleted
optional

Number of deleted events

boolean

POST /events.download_task_log

Description

Get an attachment containing the task’s log

Body parameter
Name Description Schema

task
required

Task ID

string

line_format
optional

Line string format. Used if the line type is 'text'
Default : "{asctime} {worker} {level} {msg}"

string

line_type
optional

Line format type

enum (json, text)

Responses

POST /events.get_multi_task_plots

Description

Get 'plot' events for the given tasks

Body parameter
Name Description Schema

tasks
required

List of task IDs

< string > array

iters
optional

Max number of latest iterations for which to return debug images

integer

scroll_id
optional

Scroll ID of previous call (used for getting more results)

string

Responses

Response 200

Name Description Schema

plots
optional

Plots mapping (keyed by task name)

object

returned
optional

Number of results returned

integer

scroll_id
optional

Scroll ID for getting more results

string

total
optional

Total number of results available for this query

number

POST /events.get_scalar_metric_data

Description

get scalar metric data for task

Body parameter
Name Description Schema

metric
optional

type of metric

string

task
optional

task ID

string

Responses

Response 200

Name Description Schema

events
optional

task scalar metric events

< object > array

returned
optional

amount of events returned

integer

scroll_id
optional

Scroll ID of previous call (used for getting more results)

string

total
optional

amount of events in task

integer

POST /events.get_scalar_metrics_and_variants

Description

get task scalar metrics and variants

Body parameter
Name Description Schema

task
required

task ID

string

Responses

Response 200

Name Schema

metrics
optional

object

POST /events.get_task_events

Description

Scroll through task events, sorted by timestamp

Body parameter
Name Description Schema

task
required

Task ID

string

batch_size
optional

Number of events to return each time (default 500)

integer

event_type
optional

Return only events of this type

string

order
optional

'asc' (default) or 'desc'.

enum (asc, desc)

scroll_id
optional

Pass this value on next call to get next page

string

Responses

Response 200

Name Description Schema

events
optional

Events list

< object > array

returned
optional

Number of results returned

integer

scroll_id
optional

Scroll ID for getting more results

string

total
optional

Total number of results available for this query

number

POST /events.get_task_latest_scalar_values

Description

Get the tasks’s latest scalar values

Body parameter
Name Description Schema

task
required

Task ID

string

Responses

Response 200

Name Schema

metrics
optional

< metrics > array

metrics

Name Description Schema

name
optional

Metric name

string

variants
optional

< variants > array

variants

Name Description Schema

last_100_value
optional

Average of 100 last reported values

number

last_value
optional

Last reported value

number

name
optional

Variant name

string

POST /events.get_task_log

Description

Get 'log' events for this task

Body parameter
Name Description Schema

task
required

Task ID

string

batch_size
optional

The amount of log events to return

integer

from_timestamp
optional

Epoch time in UTC ms to use as the navigation start. Optional. If not provided,
reference timestamp is determined by the 'navigate_earlier' parameter (if true,
reference timestamp is the last timestamp and if false, reference timestamp is
the first timestamp)

number

navigate_earlier
optional

If set then log events are retreived from the latest to the earliest ones (in
timestamp descending order, unless order='asc'). Otherwise from the earliest to
the latest ones (in timestamp ascending order, unless order='desc'). The
default is True

boolean

order
optional

If set, changes the order in which log events are returned based on the value
of 'navigate_earlier'

enum (asc, desc)

Responses

Response 200

Name Description Schema

events
optional

Log items list

< object > array

returned
optional

Number of log events returned

integer

total
optional

Total number of log events available for this query

number

POST /events.get_task_metrics

Description

For each task, get a list of metrics for which the requested event type was
reported

Body parameter
Name Description Schema

tasks
required

Task IDs

< string > array

event_type
optional

Event type

events.event_type_enum

Responses

Response 200

Name Description Schema

metrics
optional

List of task with their metrics

< object > array

POST /events.get_task_plots

Description

Get all 'plot' events for this task

Body parameter
Name Description Schema

task
required

Task ID

string

iters
optional

Max number of latest iterations for which to return debug images

integer

scroll_id
optional

Scroll ID of previous call (used for getting more results)

string

Responses

Response 200

Name Description Schema

plots
optional

Plots list

< object > array

returned
optional

Number of results returned

integer

scroll_id
optional

Scroll ID for getting more results

string

total
optional

Total number of results available for this query

number

POST /events.get_vector_metrics_and_variants

Body parameter
Name Description Schema

task
required

Task ID

string

Responses

Response 200

Name Schema

metrics
optional

< object > array

POST /events.multi_task_scalar_metrics_iter_histogram

Description

Used to compare scalar stats histogram of multiple tasks

Body parameter
Name Description Schema

tasks
required

List of task Task IDs. Maximum amount of tasks is 10

< string > array

key
optional

Histogram x axis to use: iter - iteration number iso_time - event time as ISO
formatted string timestamp - event timestamp as milliseconds since epoch

events.scalar_key_enum

samples
optional

The amount of histogram points to return. Optional, the default value is 6000

integer

Responses

POST /events.scalar_metrics_iter_histogram

Description

Get histogram data of all the vector metrics and variants in the task

Body parameter
Name Description Schema

task
required

Task ID

string

key
optional

Histogram x axis to use: iter - iteration number iso_time - event time as ISO
formatted string timestamp - event timestamp as milliseconds since epoch

events.scalar_key_enum

samples
optional

The amount of histogram points to return (0 to return all the points).
Optional, the default value is 6000.

integer

Responses

Response 200

Name Schema

images
optional

< object > array

POST /events.vector_metrics_iter_histogram

Description

Get histogram data of all the scalar metrics and variants in the task

Body parameter
Name Description Schema

metric
required

string

task
required

Task ID

string

variant
required

string

Responses

Response 200

Name Schema

images
optional

< object > array

Models

This service provides a management interface for models (results of training tasks) stored in the system.

POST /models.create

Description

Create a new model not associated with a task

Body parameter
Name Description Schema

name
required

Model name Unique within the company.

string

uri
required

URI for the model

string

comment
optional

Model comment

string

design
optional

Json[d] object representing the model design. Should be identical to the
network design of the task which created the model

object

framework
optional

Framework on which the model is based. Case insensitive. Should be identical to
the framework of the task which created the model.

string

labels
optional

Json object

< string, integer > map

parent
optional

Parent model

string

project
optional

Project to which to model belongs

string

public
optional

Create a public model Default is false.
Default : false

boolean

ready
optional

Indication if the model is final and can be used by other tasks. Default is
false.
Default : false

boolean

system_tags
optional

System tags. This field is reserved for system use, please don’t use it.

< string > array

tags
optional

User-defined tags

< string > array

task
optional

Associated task ID

string

Responses

Response 200

Name Description Schema

created
optional

Was the model created

boolean

id
optional

ID of the model

string

POST /models.delete

Description

Delete a model.

Body parameter
Name Description Schema

model
required

Model ID

string

force
optional

Force. Required if there are tasks that use the model as an execution model, or
if the model’s creating task is published.

boolean

Responses

Response 200

Name Description Schema

deleted
optional

Indicates whether the model was deleted

boolean

POST /models.edit

Description

Edit an existing model

Body parameter
Name Description Schema

model
required

Model ID

string

comment
optional

Model comment

string

design
optional

Json[d] object representing the model design. Should be identical to the
network design of the task which created the model

object

framework
optional

Framework on which the model is based. Case insensitive. Should be identical to
the framework of the task which created the model.

string

iteration
optional

Iteration (used to update task statistics)

integer

labels
optional

Json object

< string, integer > map

name
optional

Model name Unique within the company.

string

parent
optional

Parent model

string

project
optional

Project to which to model belongs

string

ready
optional

Indication if the model is final and can be used by other tasks

boolean

system_tags
optional

System tags. This field is reserved for system use, please don’t use it.

< string > array

tags
optional

User-defined tags

< string > array

task
optional

Associated task ID

string

uri
optional

URI for the model

string

Responses

Response 200

Name Description Schema

fields
optional

Updated fields names and values

object

updated
optional

Number of models updated (0 or 1)

integer

POST /models.get_all

Description

Get all models

Body parameter
Name Description Schema

all
optional

Multi-field pattern condition (all fields match pattern)

models.multi_field_pattern_data

any
optional

Multi-field pattern condition (any field matches pattern)

models.multi_field_pattern_data

framework
optional

List of frameworks

< string > array

id
optional

List of model IDs

< string > array

name
optional

Get only models whose name matches this pattern (python regular expression
syntax)

string

only_fields
optional

List of model field names (if applicable, nesting is supported using '.'). If
provided, this list defines the query’s projection (only these fields will be
returned for each result entry)

< string > array

order_by
optional

List of field names to order by. When search_text is used, '@text_score' can be
used as a field representing the text score of returned documents. Use '-'
prefix to specify descending order. Optional, recommended when using page

< string > array

page
optional

Page number, returns a specific page out of the resulting list of models
Minimum value : 0

integer

page_size
optional

Page size, specifies the number of results returned in each page (last page may
contain fewer results)
Minimum value : 1

integer

project
optional

List of associated project IDs

< string > array

ready
optional

Indication whether to retrieve only models that are marked ready If not
supplied returns both ready and not-ready projects.

boolean

search_text
optional

Free text search query

string

system_tags
optional

System tags list used to filter results. Prepend '-' to system tag name to
indicate exclusion

< string > array

tags
optional

User-defined tags list used to filter results. Prepend '-' to tag name to
indicate exclusion

< string > array

task
optional

List of associated task IDs

< string > array

uri
optional

List of model URIs

< string > array

user
optional

List of user IDs used to filter results by the model’s creating user

< string > array

Responses

Response 200

Name Description Schema

models
optional

Models list

< models.model > array

POST /models.get_all_ex

Description

Get all models

Body parameter
Name Description Schema

all
optional

Multi-field pattern condition (all fields match pattern)

models.multi_field_pattern_data

any
optional

Multi-field pattern condition (any field matches pattern)

models.multi_field_pattern_data

framework
optional

List of frameworks

< string > array

id
optional

List of model IDs

< string > array

name
optional

Get only models whose name matches this pattern (python regular expression
syntax)

string

only_fields
optional

List of model field names (if applicable, nesting is supported using '.'). If
provided, this list defines the query’s projection (only these fields will be
returned for each result entry)

< string > array

order_by
optional

List of field names to order by. When search_text is used, '@text_score' can be
used as a field representing the text score of returned documents. Use '-'
prefix to specify descending order. Optional, recommended when using page

< string > array

page
optional

Page number, returns a specific page out of the resulting list of models
Minimum value : 0

integer

page_size
optional

Page size, specifies the number of results returned in each page (last page may
contain fewer results)
Minimum value : 1

integer

project
optional

List of associated project IDs

< string > array

ready
optional

Indication whether to retrieve only models that are marked ready If not
supplied returns both ready and not-ready projects.

boolean

search_text
optional

Free text search query

string

system_tags
optional

System tags list used to filter results. Prepend '-' to system tag name to
indicate exclusion

< string > array

tags
optional

User-defined tags list used to filter results. Prepend '-' to tag name to
indicate exclusion

< string > array

task
optional

List of associated task IDs

< string > array

uri
optional

List of model URIs

< string > array

user
optional

List of user IDs used to filter results by the model’s creating user

< string > array

Responses

Response 200

Name Description Schema

models
optional

Models list

< models.model > array

POST /models.get_by_id

Description

Gets model information

Body parameter
Name Description Schema

model
required

Model id

string

Responses

Response 200

Name Description Schema

model
optional

Model info

models.model

POST /models.get_by_task_id

Description

Gets model information

Body parameter
Name Description Schema

task
optional

Task id

string

Responses

Response 200

Name Description Schema

model
optional

Model info

models.model

POST /models.get_frameworks

Description

Get the list of frameworks used in the company models

Body parameter
Name Description Schema

projects
optional

The list of projects which models will be analyzed. If not passed or empty then
all the company and public models will be analyzed

< string > array

Responses

Response 200

Name Description Schema

frameworks
optional

Unique list of the frameworks used in the company models

< string > array

POST /models.make_private

Description

Convert public models to private

Body parameter
Name Description Schema

ids
optional

Ids of the models to convert. Only the models originated by the company can be
converted

< string > array

Responses

Response 200

Name Description Schema

updated
optional

Number of models updated

integer

POST /models.make_public

Description

Convert company models to public

Body parameter
Name Description Schema

ids
optional

Ids of the models to convert

< string > array

Responses

Response 200

Name Description Schema

updated
optional

Number of models updated

integer

POST /models.set_ready

Description

Set the model ready flag to True. If the model is an output model of a task
then try to publish the task.

Body parameter
Name Description Schema

model
required

Model id

string

force_publish_task
optional

Publish the associated task (if exists) even if it is not in the 'stopped'
state. Optional, the default value is False.

boolean

publish_task
optional

Indicates that the associated task (if exists) should be published. Optional,
the default value is True.

boolean

Responses

Response 200

Name Description Schema

published_task
optional

Result of publishing of the model’s associated task (if exists). Returned only
if the task was published successfully as part of the model publishing.

published_task

updated
optional

Number of models updated (0 or 1)

integer

published_task

Name Description Schema

data
optional

Data returned from the task publishing operation.

data

id
optional

Task id

string

data

Name Description Schema

committed_versions_results
optional

Committed versions results

< object > array

fields
optional

Updated fields names and values

object

updated
optional

Number of tasks updated (0 or 1)

integer

POST /models.update

Description

Update a model

Body parameter
Name Description Schema

model
required

Model id

string

comment
optional

Model comment

string

created
optional

Model creation time (UTC)

string (date-time)

iteration
optional

Iteration (used to update task statistics if an associated task is reported)

integer

name
optional

Model name Unique within the company.

string

project
optional

Project to which to model belongs

string

ready
optional

Indication if the model is final and can be used by other tasks Default is
false.
Default : false

boolean

system_tags
optional

System tags. This field is reserved for system use, please don’t use it.

< string > array

tags
optional

User-defined tags

< string > array

task
optional

Associated task ID

string

ui_cache
optional

UI cache for this model

object

Responses

Response 200

Name Description Schema

fields
optional

Updated fields names and values

object

updated
optional

Number of models updated (0 or 1)

integer

POST /models.update_for_task

Description

Create or update a new model for a task

Body parameter
Name Description Schema

task
required

Task id

string

comment
optional

Model comment

string

iteration
optional

Iteration (used to update task statistics)

integer

name
optional

Model name Unique within the company.

string

override_model_id
optional

Override model ID. If provided, this model is updated in the task. Exactly one
of override_model_id or uri is required.

string

system_tags
optional

System tags. This field is reserved for system use, please don’t use it.

< string > array

tags
optional

User-defined tags

< string > array

uri
optional

URI for the model. Exactly one of uri or override_model_id is a required.

string

Responses

Response 200

Name Description Schema

created
optional

Was the model created

boolean

fields
optional

Updated fields names and values

object

id
optional

ID of the model

string

updated
optional

Number of models updated (0 or 1)

integer

Organization

This service provides organization level operations

POST /organization.get_tags

Description

Get all the user and system tags used for the company tasks and models

Body parameter
Name Description Schema

filter
optional

Filter on entities to collect tags from

filter

include_system
optional

If set to 'true' then the list of the system tags is also returned. The default
value is 'false'
Default : false

boolean

filter

Name Description Schema

system_tags
optional

The list of system tag values to filter by. Use 'null' value to specify empty system tags. Use '__Snot' value to specify that the following value should be excluded

< string > array

tags
optional

The list of tag values to filter by. Use 'null' value to specify empty tags. Use '__Snot' value to specify that the following value should be excluded

< string > array

Responses

Response 200

Name Description Schema

system_tags
optional

The list of unique system tag values. Returned only if 'include_system' is set
to 'true' in the request

< string > array

tags
optional

The list of unique tag values

< string > array

Projects

Provides support for defining Projects containing Tasks, Models and Dataset Versions.

POST /projects.create

Description

Create a new project

Body parameter
Name Description Schema

description
required

Project description.

string

name
required

Project name Unique within the company.

string

default_output_destination
optional

The default output destination URL for new tasks under this project

string

system_tags
optional

System tags. This field is reserved for system use, please don’t use it.

< string > array

tags
optional

User-defined tags

< string > array

Responses

Response 200

Name Description Schema

id
optional

Project id

string

POST /projects.delete

Description

Deletes a project

Body parameter
Name Description Schema

project
required

Project id

string

force
optional

If not true, fails if project has tasks. If true, and project has tasks, they
will be unassigned
Default : false

boolean

Responses

Response 200

Name Description Schema

deleted
optional

Number of projects deleted (0 or 1)

integer

disassociated_tasks
optional

Number of tasks disassociated from the deleted project

integer

POST /projects.get_all

Description

Get all the company’s projects and all public projects

Body parameter
Name Description Schema

all
optional

Multi-field pattern condition (all fields match pattern)

projects.multi_field_pattern_data

any
optional

Multi-field pattern condition (any field matches pattern)

projects.multi_field_pattern_data

description
optional

Get only projects whose description matches this pattern (python regular
expression syntax)

string

id
optional

List of IDs to filter by

< string > array

name
optional

Get only projects whose name matches this pattern (python regular expression
syntax)

string

only_fields
optional

List of document’s field names (nesting is supported using '.', e.g.
execution.model_labels). If provided, this list defines the query’s projection
(only these fields will be returned for each result entry)

< string > array

order_by
optional

List of field names to order by. When search_text is used, '@text_score' can be
used as a field representing the text score of returned documents. Use '-'
prefix to specify descending order. Optional, recommended when using page

< string > array

page
optional

Page number, returns a specific page out of the resulting list of dataviews
Minimum value : 0

integer

page_size
optional

Page size, specifies the number of results returned in each page (last page may
contain fewer results)
Minimum value : 1

integer

search_text
optional

Free text search query

string

system_tags
optional

System tags list used to filter results. Prepend '-' to system tag name to
indicate exclusion

< string > array

tags
optional

User-defined tags list used to filter results. Prepend '-' to tag name to
indicate exclusion

< string > array

Responses

Response 200

Name Description Schema

projects
optional

Projects list

< projects.projects_get_all_response_single > array

POST /projects.get_all_ex

Description

Get all the company’s projects and all public projects

Body parameter
Name Description Schema

all
optional

Multi-field pattern condition (all fields match pattern)

projects.multi_field_pattern_data

any
optional

Multi-field pattern condition (any field matches pattern)

projects.multi_field_pattern_data

description
optional

Get only projects whose description matches this pattern (python regular
expression syntax)

string

id
optional

List of IDs to filter by

< string > array

include_stats
optional

If true, include project statistic in response.
Default : false

boolean

name
optional

Get only projects whose name matches this pattern (python regular expression
syntax)

string

non_public
optional

Return only non-public projects
Default : false

boolean

only_fields
optional

List of document’s field names (nesting is supported using '.', e.g.
execution.model_labels). If provided, this list defines the query’s projection
(only these fields will be returned for each result entry)

< string > array

order_by
optional

List of field names to order by. When search_text is used, '@text_score' can be
used as a field representing the text score of returned documents. Use '-'
prefix to specify descending order. Optional, recommended when using page

< string > array

page
optional

Page number, returns a specific page out of the resulting list of dataviews
Minimum value : 0

integer

page_size
optional

Page size, specifies the number of results returned in each page (last page may
contain fewer results)
Minimum value : 1

integer

search_text
optional

Free text search query

string

stats_for_state
optional

Report stats include only statistics for tasks in the specified state. If Null
is provided, stats for all task states will be returned.
Default : "active"

enum (active, archived)

system_tags
optional

System tags list used to filter results. Prepend '-' to system tag name to
indicate exclusion

< string > array

tags
optional

User-defined tags list used to filter results. Prepend '-' to tag name to
indicate exclusion

< string > array

Responses

Response 200

Name Description Schema

projects
optional

Projects list

< projects.projects_get_all_response_single > array

POST /projects.get_by_id

Body parameter
Name Description Schema

project
required

Project id

string

Responses

Response 200

Name Description Schema

project
optional

Project info

projects.project

POST /projects.get_hyper_parameters

Description

Get a list of all hyper parameter sections and names used in tasks within the
given project.

Body parameter
Name Description Schema

page
optional

Page number

integer

page_size
optional

Page size

integer

project
optional

Project ID

string

Responses

Response 200

Name Description Schema

parameters
optional

A list of parameter sections and names

< object > array

remaining
optional

Remaining results

integer

total
optional

Total number of results

integer

POST /projects.get_model_tags

Description

Get user and system tags used for the models under the specified projects

Body parameter
Name Description Schema

filter
optional

Filter on entities to collect tags from

filter

include_system
optional

If set to 'true' then the list of the system tags is also returned. The default
value is 'false'
Default : false

boolean

projects
optional

The list of projects under which the tags are searched. If not passed or empty
then all the projects are searched

< string > array

filter

Name Description Schema

system_tags
optional

The list of system tag values to filter by. Use 'null' value to specify empty system tags. Use '__Snot' value to specify that the following value should be excluded

< string > array

tags
optional

The list of tag values to filter by. Use 'null' value to specify empty tags. Use '__Snot' value to specify that the following value should be excluded

< string > array

Responses

Response 200

Name Description Schema

system_tags
optional

The list of unique system tag values. Returned only if 'include_system' is set
to 'true' in the request

< string > array

tags
optional

The list of unique tag values

< string > array

POST /projects.get_task_tags

Description

Get user and system tags used for the tasks under the specified projects

Body parameter
Name Description Schema

filter
optional

Filter on entities to collect tags from

filter

include_system
optional

If set to 'true' then the list of the system tags is also returned. The default
value is 'false'
Default : false

boolean

projects
optional

The list of projects under which the tags are searched. If not passed or empty
then all the projects are searched

< string > array

filter

Name Description Schema

system_tags
optional

The list of system tag values to filter by. Use 'null' value to specify empty system tags. Use '__Snot' value to specify that the following value should be excluded

< string > array

tags
optional

The list of tag values to filter by. Use 'null' value to specify empty tags. Use '__Snot' value to specify that the following value should be excluded

< string > array

Responses

Response 200

Name Description Schema

system_tags
optional

The list of unique system tag values. Returned only if 'include_system' is set
to 'true' in the request

< string > array

tags
optional

The list of unique tag values

< string > array

POST /projects.get_unique_metric_variants

Description

Get all metric/variant pairs reported for tasks in a specific project. If no
project is specified, metrics/variant paris reported for all tasks will be
returned. If the project does not exist, an empty list will be returned.

Body parameter
Name Description Schema

project
optional

Project ID

string

Responses

Response 200

Name Description Schema

metrics
optional

A list of metric variants reported for tasks in this project

< projects.metric_variant_result > array

POST /projects.make_private

Description

Convert public projects to private

Body parameter
Name Description Schema

ids
optional

Ids of the projects to convert. Only the projects originated by the company can
be converted

< string > array

Responses

Response 200

Name Description Schema

updated
optional

Number of projects updated

integer

POST /projects.make_public

Description

Convert company projects to public

Body parameter
Name Description Schema

ids
optional

Ids of the projects to convert

< string > array

Responses

Response 200

Name Description Schema

updated
optional

Number of projects updated

integer

POST /projects.update

Description

Update project information

Body parameter
Name Description Schema

project
required

Project id

string

default_output_destination
optional

The default output destination URL for new tasks under this project

string

description
optional

Project description

string

name
optional

Project name. Unique within the company.

string

system_tags
optional

System tags. This field is reserved for system use, please don’t use it.

< string > array

tags
optional

User-defined tags

< string > array

Responses

Response 200

Name Description Schema

fields
optional

Updated fields names and values

object

updated
optional

Number of projects updated (0 or 1)

integer

Queues

Provides a management API for queues of tasks waiting to be executed by workers deployed anywhere (see Workers Service).

POST /queues.add_task

Description

Adds a task entry to the queue.

Body parameter
Name Description Schema

queue
required

Queue id

string

task
required

Task id

string

Responses

Response 200

Name Description Schema

added
optional

Number of tasks added (0 or 1)

integer

POST /queues.create

Description

Create a new queue

Body parameter
Name Description Schema

name
required

Queue name Unique within the company.

string

system_tags
optional

System tags list. This field is reserved for system use, please don’t use it.

< string > array

tags
optional

User-defined tags list

< string > array

Responses

Response 200

Name Description Schema

id
optional

New queue ID

string

POST /queues.delete

Description

Deletes a queue. If the queue is not empty and force is not set to true, queue
will not be deleted.

Body parameter
Name Description Schema

queue
required

Queue id

string

force
optional

Force delete of non-empty queue. Defaults to false
Default : false

boolean

Responses

Response 200

Name Description Schema

deleted
optional

Number of queues deleted (0 or 1)

integer

POST /queues.get_all

Description

Get all queues

Body parameter
Name Description Schema

id
optional

List of Queue IDs used to filter results

< string > array

name
optional

Get only queues whose name matches this pattern (python regular expression
syntax)

string

only_fields
optional

List of document field names (nesting is supported using '.', e.g.
execution.model_labels). If provided, this list defines the query’s projection
(only these fields will be returned for each result entry)

< string > array

order_by
optional

List of field names to order by. When search_text is used, '@text_score' can be
used as a field representing the text score of returned documents. Use '-'
prefix to specify descending order. Optional, recommended when using page

< string > array

page
optional

Page number, returns a specific page out of the result list of results.
Minimum value : 0

integer

page_size
optional

Page size, specifies the number of results returned in each page (last page may
contain fewer results)
Minimum value : 1

integer

search_text
optional

Free text search query

string

system_tags
optional

System tags list used to filter results. Prepend '-' to system tag name to
indicate exclusion

< string > array

tags
optional

User-defined tags list used to filter results. Prepend '-' to tag name to
indicate exclusion

< string > array

Responses

Response 200

Name Description Schema

queues
optional

Queues list

< queues.queue > array

POST /queues.get_all_ex

Description

Get all queues

Body parameter
Name Description Schema

id
optional

List of Queue IDs used to filter results

< string > array

name
optional

Get only queues whose name matches this pattern (python regular expression
syntax)

string

only_fields
optional

List of document field names (nesting is supported using '.', e.g.
execution.model_labels). If provided, this list defines the query’s projection
(only these fields will be returned for each result entry)

< string > array

order_by
optional

List of field names to order by. When search_text is used, '@text_score' can be
used as a field representing the text score of returned documents. Use '-'
prefix to specify descending order. Optional, recommended when using page

< string > array

page
optional

Page number, returns a specific page out of the result list of results.
Minimum value : 0

integer

page_size
optional

Page size, specifies the number of results returned in each page (last page may
contain fewer results)
Minimum value : 1

integer

search_text
optional

Free text search query

string

system_tags
optional

System tags list used to filter results. Prepend '-' to system tag name to
indicate exclusion

< string > array

tags
optional

User-defined tags list used to filter results. Prepend '-' to tag name to
indicate exclusion

< string > array

Responses

Response 200

Name Description Schema

queues
optional

Queues list

< queues.queue > array

POST /queues.get_by_id

Description

Gets queue information

Body parameter
Name Description Schema

queue
required

Queue ID

string

Responses

Response 200

Name Description Schema

queue
optional

Queue info

queues.queue

POST /queues.get_default

Body parameter
Responses

Response 200

Name Description Schema

id
optional

Queue id

string

name
optional

Queue name

string

POST /queues.get_next_task

Description

Gets the next task from the top of the queue (FIFO). The task entry is removed
from the queue.

Body parameter
Name Description Schema

queue
required

Queue id

string

Responses

Response 200

Name Description Schema

entry
optional

Entry information

queues.entry

POST /queues.get_queue_metrics

Description

Returns metrics of the company queues. The metrics are avaraged in the
specified interval.

Body parameter
Name Description Schema

from_date
required

Starting time (in seconds from epoch) for collecting metrics

number

interval
required

Time interval in seconds for a single metrics point. The minimal value is 1

integer

to_date
required

Ending time (in seconds from epoch) for collecting metrics

number

queue_ids
optional

List of queue ids to collect metrics for. If not provided or empty then all
then average metrics across all the company queues will be returned.

< string > array

Responses

Response 200

Name Description Schema

queues
optional

List of the requested queues with their metrics. If no queue ids were requested
then 'all' queue is returned with the metrics averaged accross all the company
queues.

< queues.queue_metrics > array

POST /queues.move_task_backward

Body parameter
Name Description Schema

queue
required

Queue id

string

task
required

Task id

string

count
optional

Number of positions in the queue to move the task forward relative to the
current position. Optional, the default value is 1.

integer

Responses

Response 200

Name Description Schema

position
optional

The new position of the task entry in the queue (index, -1 represents bottom of
queue)

integer

POST /queues.move_task_forward

Description

Moves a task entry one step forward towards the top of the queue.

Body parameter
Name Description Schema

queue
required

Queue id

string

task
required

Task id

string

count
optional

Number of positions in the queue to move the task forward relative to the
current position. Optional, the default value is 1.

integer

Responses

Response 200

Name Description Schema

position
optional

The new position of the task entry in the queue (index, -1 represents bottom of
queue)

integer

POST /queues.move_task_to_back

Body parameter
Name Description Schema

queue
required

Queue id

string

task
required

Task id

string

Responses

Response 200

Name Description Schema

position
optional

The new position of the task entry in the queue (index, -1 represents bottom of
queue)

integer

POST /queues.move_task_to_front

Body parameter
Name Description Schema

queue
required

Queue id

string

task
required

Task id

string

Responses

Response 200

Name Description Schema

position
optional

The new position of the task entry in the queue (index, -1 represents bottom of
queue)

integer

POST /queues.remove_task

Description

Removes a task entry from the queue.

Body parameter
Name Description Schema

queue
required

Queue id

string

task
required

Task id

string

Responses

Response 200

Name Description Schema

removed
optional

Number of tasks removed (0 or 1)

integer

POST /queues.update

Description

Update queue information

Body parameter
Name Description Schema

queue
required

Queue id

string

name
optional

Queue name Unique within the company.

string

system_tags
optional

System tags list. This field is reserved for system use, please don’t use it.

< string > array

tags
optional

User-defined tags list

< string > array

Responses

Response 200

Name Description Schema

fields
optional

Updated fields names and values

object

updated
optional

Number of queues updated (0 or 1)

integer

Server

server utilities

Tasks

Provides a management API for tasks in the system.

POST /tasks.add_or_update_artifacts

Description

Update an existing artifact (search by key/mode) or add a new one

Body parameter
Name Description Schema

artifacts
required

Artifacts to add or update

< tasks.artifact > array

task
required

Task ID

string

Responses

Response 200

Name Description Schema

added
optional

Keys of artifacts added

< string > array

updated
optional

Keys of artifacts updated

< string > array

POST /tasks.clone

Description

Clone an existing task

Body parameter
Name Description Schema

task
required

ID of the task

string

execution_overrides
optional

The execution params for the cloned task. The params not specified are taken
from the original task

tasks.execution

new_task_comment
optional

The comment of the cloned task. If not provided then taken from the original
task

string

new_task_configuration
optional

The configuration for the new task. If not provided then taken from the
original task

< string, tasks.configuration_item > map

new_task_hyperparams
optional

The hyper params for the new task. If not provided then taken from the original
task

< string, tasks.section_params > map

new_task_name
optional

The name of the cloned task. If not provided then taken from the original task

string

new_task_parent
optional

The parent of the cloned task. If not provided then taken from the original
task

string

new_task_project
optional

The project of the cloned task. If not provided then taken from the original
task

string

new_task_system_tags
optional

The system tags of the cloned task. If not provided then empty

< string > array

new_task_tags
optional

The user-defined tags of the cloned task. If not provided then taken from the
original task

< string > array

validate_references
optional

If set to 'false' then the task fields that are copied from the original task
are not validated. The default is false.

boolean

Responses

Response 200

Name Description Schema

id
optional

ID of the new task

string

POST /tasks.close

Description

Indicates that task is closed

Body parameter
Name Description Schema

task
required

Task ID

string

force
optional

Allows forcing state change even if transition is not supported
Default : false

boolean

status_message
optional

Extra information regarding status change

string

status_reason
optional

Reason for status change

string

Responses

Response 200

Name Description Schema

fields
optional

Updated fields names and values

object

updated
optional

Number of tasks updated (0 or 1)

integer

POST /tasks.completed

Description

Signal a task has completed

Body parameter
Name Description Schema

task
required

Task ID

string

force
optional

If not true, call fails if the task status is not in_progress/stopped
Default : false

boolean

status_message
optional

Extra information regarding status change

string

status_reason
optional

Reason for status change

string

Responses

Response 200

Name Description Schema

fields
optional

Updated fields names and values

object

updated
optional

Number of tasks updated (0 or 1)

integer

POST /tasks.create

Description

Create a new task

Body parameter
Name Description Schema

name
required

Task name. Unique within the company.

string

type
required

Type of task

tasks.task_type_enum

comment
optional

Free text comment

string

configuration
optional

Task configuration params

< string, tasks.configuration_item > map

execution
optional

Task execution params

tasks.execution

hyperparams
optional

Task hyper params per section

< string, tasks.section_params > map

output_dest
optional

Output storage id Must be a reference to an existing storage.

string

parent
optional

Parent task id Must be a completed task.

string

project
optional

Project ID of the project to which this task is assigned Must exist[ab]

string

script
optional

Script info

tasks.script

system_tags
optional

System tags list. This field is reserved for system use, please don’t use it.

< string > array

tags
optional

User-defined tags list

< string > array

Responses

Response 200

Name Description Schema

id
optional

ID of the task

string

POST /tasks.delete

Description

Delete a task along with any information stored for it (statistics, frame
updates etc.) Unless Force flag is provided, operation will fail if task has
objects associated with it - i.e. children tasks and projects. Models that
refer to the deleted task will be updated with a task ID indicating a deleted
task.

Body parameter
Name Description Schema

task
required

Task ID

string

force
optional

If not true, call fails if the task status is 'in_progress'
Default : false

boolean

move_to_trash
optional

Move task to trash instead of deleting it. For internal use only, tasks in the
trash are not visible from the API and cannot be restored!
Default : false

boolean

status_message
optional

Extra information regarding status change

string

status_reason
optional

Reason for status change

string

Responses

Response 200

Name Description Schema

deleted
optional

Indicates whether the task was deleted

boolean

events
optional

Response from events.delete_for_task

object

frames
optional

Response from frames.rollback

object

updated_children
optional

Number of child tasks whose parent property was updated

integer

updated_models
optional

Number of models whose task property was updated

integer

updated_versions
optional

Number of dataset versions whose task property was updated

integer

POST /tasks.delete_configuration

Description

Delete task configuration items

Body parameter
Name Description Schema

configuration
required

List of configuration itemss to delete

< string > array

task
required

Task ID

string

Responses

Response 200

Name Description Schema

deleted
optional

Indicates if the task was updated successfully

integer

POST /tasks.delete_hyper_params

Description

Delete task hyper parameters

Body parameter
Name Description Schema

hyperparams
required

List of hyper parameters to delete. In case a parameter with an empty name is
passed all the section will be deleted

< tasks.param_key > array

task
required

Task ID

string

Responses

Response 200

Name Description Schema

deleted
optional

Indicates if the task was updated successfully

integer

POST /tasks.dequeue

Description

Remove a task from its queue. Fails if task status is not queued.

Body parameter
Name Description Schema

task
required

Task ID

string

status_message
optional

Extra information regarding status change

string

status_reason
optional

Reason for status change

string

Responses

Response 200

Name Description Schema

dequeued
optional

Number of tasks dequeued (0 or 1)

integer

fields
optional

Updated fields names and values

object

updated
optional

Number of tasks updated (0 or 1)

integer

POST /tasks.edit

Description

Edit task’s details.

Body parameter
Name Description Schema

task
required

ID of the task

string

comment
optional

Free text comment

string

configuration
optional

Task configuration params

< string, tasks.configuration_item > map

execution
optional

Task execution params

tasks.execution

force
optional

If not true, call fails if the task status is not 'created'
Default : false

boolean

hyperparams
optional

Task hyper params per section

< string, tasks.section_params > map

name
optional

Task name Unique within the company.

string

output_dest
optional

Output storage id Must be a reference to an existing storage.

string

parent
optional

Parent task id Must be a completed task.

string

project
optional

Project ID of the project to which this task is assigned Must exist[ab]

string

script
optional

Script info

tasks.script

system_tags
optional

System tags list. This field is reserved for system use, please don’t use it.

< string > array

tags
optional

User-defined tags list

< string > array

type
optional

Type of task

tasks.task_type_enum

Responses

Response 200

Name Description Schema

fields
optional

Updated fields names and values

object

updated
optional

Number of tasks updated (0 or 1)

integer

POST /tasks.edit_configuration

Description

Add or update task configuration

Body parameter
Name Description Schema

configuration
required

Task configuration items. The new ones will be added and the already existing
ones will be updated

< tasks.configuration_item > array

task
required

Task ID

string

replace_configuration
optional

If set then the all the configuration items will be replaced with the provided
ones. Otherwise only the provided configuration items will be updated or added

boolean

Responses

Response 200

Name Description Schema

updated
optional

Indicates if the task was updated successfully

integer

POST /tasks.edit_hyper_params

Description

Add or update task hyper parameters

Body parameter
Name Description Schema

hyperparams
required

Task hyper parameters. The new ones will be added and the already existing ones
will be updated

< tasks.params_item > array

task
required

Task ID

string

replace_hyperparams
optional

Can be set to one of the following: 'all' - all the hyper parameters will be
replaced with the provided ones 'section' - the sections that present in the
new parameters will be replaced with the provided parameters 'none' (the
default value) - only the specific parameters will be updated or added

tasks.replace_hyperparams_enum

Responses

Response 200

Name Description Schema

updated
optional

Indicates if the task was updated successfully

integer

POST /tasks.enqueue

Description

Adds a task into a queue.
Fails if task state is not 'created'.
Fails if the following parameters in the task were not filled:
* execution.script.repository
* execution.script.entrypoint

Body parameter
Name Description Schema

task
required

Task ID

string

queue
optional

Queue id. If not provided, task is added to the default queue.

string

status_message
optional

Extra information regarding status change

string

status_reason
optional

Reason for status change

string

Responses

Response 200

Name Description Schema

fields
optional

Updated fields names and values

object

queued
optional

Number of tasks queued (0 or 1)

integer

updated
optional

Number of tasks updated (0 or 1)

integer

POST /tasks.failed

Description

Indicates that task has failed

Body parameter
Name Description Schema

task
required

Task ID

string

force
optional

Allows forcing state change even if transition is not supported
Default : false

boolean

status_message
optional

Extra information regarding status change

string

status_reason
optional

Reason for status change

string

Responses

Response 200

Name Description Schema

fields
optional

Updated fields names and values

object

updated
optional

Number of tasks updated (0 or 1)

integer

POST /tasks.get_all

Description

Get all the company’s tasks and all public tasks

Body parameter
Name Description Schema

all
optional

Multi-field pattern condition (all fields match pattern)

tasks.multi_field_pattern_data

any
optional

Multi-field pattern condition (any field matches pattern)

tasks.multi_field_pattern_data

id
optional

List of IDs to filter by

< string > array

name
optional

Get only tasks whose name matches this pattern (python regular expression
syntax)

string

only_fields
optional

List of task field names (nesting is supported using '.', e.g.
execution.model_labels). If provided, this list defines the query’s projection
(only these fields will be returned for each result entry)

< string > array

order_by
optional

List of field names to order by. When search_text is used, '@text_score' can be
used as a field representing the text score of returned documents. Use '-'
prefix to specify descending order. Optional, recommended when using page. If
the first order field is a hyper parameter or metric then string values are
ordered according to numeric ordering rules where applicable

< string > array

page
optional

Page number, returns a specific page out of the resulting list of tasks
Minimum value : 0

integer

page_size
optional

Page size, specifies the number of results returned in each page (last page may
contain fewer results)
Minimum value : 1

integer

parent
optional

Parent ID

string

project
optional

List of project IDs

< string > array

search_text
optional

Free text search query

string

status
optional

List of task status.

< tasks.task_status_enum > array

status_changed
optional

List of status changed constraint strings (utcformat, epoch) with an optional
prefix modifier (>, >=, <, <=)

< string > array

system_tags
optional

List of task system tags. Use '-' prefix to exclude system tags

< string > array

tags
optional

List of task user-defined tags. Use '-' prefix to exclude tags

< string > array

type
optional

List of task types. One or more of: 'import', 'annotation', 'training' or
'testing' (case insensitive)

< string > array

user
optional

List of user IDs used to filter results by the task’s creating user

< string > array

Responses

Response 200

Name Description Schema

tasks
optional

List of tasks

< tasks.task > array

POST /tasks.get_all_ex

Description

Get all the company’s tasks and all public tasks

Body parameter
Name Description Schema

all
optional

Multi-field pattern condition (all fields match pattern)

tasks.multi_field_pattern_data

any
optional

Multi-field pattern condition (any field matches pattern)

tasks.multi_field_pattern_data

id
optional

List of IDs to filter by

< string > array

name
optional

Get only tasks whose name matches this pattern (python regular expression
syntax)

string

only_fields
optional

List of task field names (nesting is supported using '.', e.g.
execution.model_labels). If provided, this list defines the query’s projection
(only these fields will be returned for each result entry)

< string > array

order_by
optional

List of field names to order by. When search_text is used, '@text_score' can be
used as a field representing the text score of returned documents. Use '-'
prefix to specify descending order. Optional, recommended when using page. If
the first order field is a hyper parameter or metric then string values are
ordered according to numeric ordering rules where applicable

< string > array

page
optional

Page number, returns a specific page out of the resulting list of tasks
Minimum value : 0

integer

page_size
optional

Page size, specifies the number of results returned in each page (last page may
contain fewer results)
Minimum value : 1

integer

parent
optional

Parent ID

string

project
optional

List of project IDs

< string > array

search_text
optional

Free text search query

string

status
optional

List of task status.

< tasks.task_status_enum > array

status_changed
optional

List of status changed constraint strings (utcformat, epoch) with an optional
prefix modifier (>, >=, <, <=)

< string > array

system_tags
optional

List of task system tags. Use '-' prefix to exclude system tags

< string > array

tags
optional

List of task user-defined tags. Use '-' prefix to exclude tags

< string > array

type
optional

List of task types. One or more of: 'import', 'annotation', 'training' or
'testing' (case insensitive)

< string > array

user
optional

List of user IDs used to filter results by the task’s creating user

< string > array

Responses

Response 200

Name Description Schema

tasks
optional

List of tasks

< tasks.task > array

POST /tasks.get_by_id

Description

Gets task information

Body parameter
Name Description Schema

task
required

Task ID

string

Responses

Response 200

Name Description Schema

task
optional

Task info

tasks.task

POST /tasks.get_configuration_names

Description

Get the list of task configuration items names

Body parameter
Name Description Schema

tasks
required

Task IDs

< string > array

Responses

Response 200

Name Description Schema

configurations
optional

Names of task configuration items (keyed by task ID)

object

POST /tasks.get_configurations

Description

Get the list of task configurations

Body parameter
Name Description Schema

tasks
required

Task IDs

< string > array

names
optional

Names of the configuration items to retreive. If not passed or empty then all
the configurations will be retreived.

< string > array

Responses

Response 200

Name Description Schema

configurations
optional

Configurations (keyed by task ID)

object

POST /tasks.get_hyper_params

Description

Get the list of task hyper parameters

Body parameter
Name Description Schema

tasks
required

Task IDs

< string > array

Responses

Response 200

Name Description Schema

params
optional

Hyper parameters (keyed by task ID)

object

POST /tasks.get_types

Description

Get the list of task types used in the specified projects

Body parameter
Name Description Schema

projects
optional

The list of projects which tasks will be analyzed. If not passed or empty then
all the company and public tasks will be analyzed

< string > array

Responses

Response 200

Name Description Schema

types
optional

Unique list of the task types used in the requested projects

< string > array

POST /tasks.make_private

Description

Convert public tasks to private

Body parameter
Name Description Schema

ids
optional

Ids of the tasks to convert. Only the tasks originated by the company can be
converted

< string > array

Responses

Response 200

Name Description Schema

updated
optional

Number of tasks updated

integer

POST /tasks.make_public

Description

Convert company tasks to public

Body parameter
Name Description Schema

ids
optional

Ids of the tasks to convert

< string > array

Responses

Response 200

Name Description Schema

updated
optional

Number of tasks updated

integer

POST /tasks.ping

Description

Refresh the task’s last update time

Body parameter
Name Description Schema

task
required

Task ID

string

Responses

POST /tasks.publish

Description

Mark a task status as published.
For Annotation tasks - if any changes were committed by this task, a
new version in the dataset together with an output view are created.
For Training tasks - if a model was created, it should be set to ready.

Body parameter
Name Description Schema

task
required

Task ID

string

force
optional

If not true, call fails if the task status is not 'stopped'
Default : false

boolean

publish_model
optional

Indicates that the task output model (if exists) should be published. Optional,
the default value is True.

boolean

status_message
optional

Extra information regarding status change

string

status_reason
optional

Reason for status change

string

Responses

Response 200

Name Description Schema

committed_versions_results
optional

Committed versions results

< object > array

fields
optional

Updated fields names and values

object

updated
optional

Number of tasks updated (0 or 1)

integer

POST /tasks.reset

Description

Reset a task to its initial state, along with any information stored for it
(statistics, frame updates etc.).

Body parameter
Name Description Schema

task
required

Task ID

string

clear_all
optional

Clear script and execution sections completely
Default : false

boolean

force
optional

If not true, call fails if the task status is 'completed'
Default : false

boolean

status_message
optional

Extra information regarding status change

string

status_reason
optional

Reason for status change

string

Responses

Response 200

Name Description Schema

deleted_indices
optional

List of deleted ES indices that were removed as part of the reset process

< string > array

deleted_models
optional

Number of output models deleted by the reset

integer

dequeued
optional

Response from queues.remove_task

object

events
optional

Response from events.delete_for_task

object

fields
optional

Updated fields names and values

object

frames
optional

Response from frames.rollback

object

updated
optional

Number of tasks updated (0 or 1)

integer

POST /tasks.set_requirements

Description

Set the script requirements for a task

Body parameter
Name Description Schema

requirements
required

A JSON object containing requirements strings by key

object

task
required

Task ID

string

Responses

Response 200

Name Description Schema

fields
optional

Updated fields names and values

object

updated
optional

Number of tasks updated (0 or 1)

integer

POST /tasks.started

Description

Mark a task status as in_progress. Optionally allows to set the task’s
execution progress.

Body parameter
Name Description Schema

task
required

Task ID

string

force
optional

If not true, call fails if the task status is not 'not_started'
Default : false

boolean

status_message
optional

Extra information regarding status change

string

status_reason
optional

Reason for status change

string

Responses

Response 200

Name Description Schema

fields
optional

Updated fields names and values

object

started
optional

Number of tasks started (0 or 1)

integer

updated
optional

Number of tasks updated (0 or 1)

integer

POST /tasks.stop

Description

Request to stop a running task

Body parameter
Name Description Schema

task
required

Task ID

string

force
optional

If not true, call fails if the task status is not 'in_progress'
Default : false

boolean

status_message
optional

Extra information regarding status change

string

status_reason
optional

Reason for status change

string

Responses

Response 200

Name Description Schema

fields
optional

Updated fields names and values

object

updated
optional

Number of tasks updated (0 or 1)

integer

POST /tasks.stopped

Description

Signal a task has stopped

Body parameter
Name Description Schema

task
required

Task ID

string

force
optional

If not true, call fails if the task status is not 'stopped'
Default : false

boolean

status_message
optional

Extra information regarding status change

string

status_reason
optional

Reason for status change

string

Responses

Response 200

Name Description Schema

fields
optional

Updated fields names and values

object

updated
optional

Number of tasks updated (0 or 1)

integer

POST /tasks.update

Description

Update task’s runtime parameters

Body parameter
Name Description Schema

task
required

ID of the task

string

comment
optional

Free text comment

string

created
optional

Task creation time (UTC)

string (date-time)

name
optional

Task name Unique within the company.

string

outputerror
optional__

Free text error

string

project
optional

Project ID of the project to which this task is assigned

string

system_tags
optional

System tags list. This field is reserved for system use, please don’t use it.

< string > array

tags
optional

User-defined tags list

< string > array

Responses

Response 200

Name Description Schema

fields
optional

Updated fields names and values

object

updated
optional

Number of tasks updated (0 or 1)

integer

POST /tasks.update_batch

Description

Updates a batch of tasks. Headers Content type should be 'application/json-
lines'.

Body parameter

Json encoded newline-terminated lines, each representing an event in the batch and uses the same parameters used for tasks.update

Responses

Response 200

Name Description Schema

updated
optional

Number of tasks updated (0 or 1)

integer

POST /tasks.validate

Description

Validate task properties (before create)

Body parameter
Name Description Schema

name
required

Task name. Unique within the company.

string

type
required

Type of task

tasks.task_type_enum

comment
optional

Free text comment

string

configuration
optional

Task configuration params

< string, tasks.configuration_item > map

execution
optional

Task execution params

tasks.execution

hyperparams
optional

Task hyper params per section

< string, tasks.section_params > map

output_dest
optional

Output storage id Must be a reference to an existing storage.

string

parent
optional

Parent task id Must be a completed task.

string

project
optional

Project ID of the project to which this task is assigned Must exist[ab]

string

script
optional

Script info

tasks.script

system_tags
optional

System tags list. This field is reserved for system use, please don’t use it.

< string > array

tags
optional

User-defined tags list

< string > array

Responses

Users

This service provides a management interface to users information and new users login restrictions.

Workers

Provides an API for worker machines, allowing workers to report status and get tasks for execution

POST /workers.get_activity_report

Description

Returns count of active company workers in the selected time range.

Body parameter
Name Description Schema

from_date
required

Starting time (in seconds from epoch) for collecting statistics

number

interval
required

Time interval in seconds for a single statistics point. The minimal value is 1

integer

to_date
required

Ending time (in seconds from epoch) for collecting statistics

number

Responses

Response 200

Name Description Schema

active
optional

Activity series that include only workers that worked on a task in the given
time interval.

workers.activity_series

total
optional

Activity series that include all the workers that sent reports in the given
time interval.

workers.activity_series

POST /workers.get_all

Description

Returns information on all registered workers.

Body parameter
Name Description Schema

last_seen
optional

Filter out workers not active for more than last_seen seconds. A value or 0 or
'none' will disable the filter.

integer

Responses

Response 200

Name Schema

workers
optional

< workers.worker > array

POST /workers.get_metric_keys

Description

Returns worker statistics metric keys grouped by categories.

Body parameter
Name Description Schema

worker_ids
optional

List of worker ids to collect metrics for. If not provided or empty then all
the company workers metrics are analyzed.

< string > array

Responses

Response 200

Name Description Schema

categories
optional

List of unique metric categories found in the statistics of the requested
workers.

< workers.metrics_category > array

POST /workers.get_stats

Description

Returns statistics for the selected workers and time range aggregated by date
intervals.

Body parameter
Name Description Schema

from_date
required

Starting time (in seconds from epoch) for collecting statistics

number

interval
required

Time interval in seconds for a single statistics point. The minimal value is 1

integer

items
required

List of metric keys and requested statistics

< workers.stat_item > array

to_date
required

Ending time (in seconds from epoch) for collecting statistics

number

split_by_variant
optional

If true then break statistics by hardware sub types
Default : false

boolean

worker_ids
optional

List of worker ids to collect metrics for. If not provided or empty then all
the company workers metrics are analyzed.

< string > array

Responses

Response 200

Name Description Schema

workers
optional

List of the requested workers with their statistics

< workers.worker_stats > array

POST /workers.register

Description

Register a worker in the system. Called by the Worker Daemon.

Body parameter
Name Description Schema

worker
required

Worker id. Must be unique in company.

string

queues
optional

List of queue IDs on which the worker is listening.

< string > array

tags
optional

User tags for the worker

< string > array

timeout
optional

Registration timeout in seconds. If timeout seconds have passed since the
worker’s last call to register or status_report, the worker is automatically
removed from the list of registered workers.

integer

Responses

POST /workers.status_report

Description

Called periodically by the worker daemon to report machine status

Body parameter
Name Description Schema

timestamp
required

UNIX time in seconds since epoch.

integer

worker
required

Worker id.

string

machine_stats
optional

The machine statistics.

workers.machine_stats

queue
optional

ID of the queue from which task was received. If no queue is sent, the worker’s
queue field will be cleared.

string

queues
optional

List of queue IDs on which the worker is listening. If null, the worker’s
queues list will not be updated.

< string > array

tags
optional

New user tags for the worker

< string > array

task
optional

ID of a task currently being run by the worker. If no task is sent, the
worker’s task field will be cleared.

string

Responses

POST /workers.unregister

Description

Unregister a worker in the system. Called by the Worker Daemon.

Body parameter
Name Description Schema

worker
required

Worker id. Must be unique in company.

string

Responses

Definitions

auth.credential_key

Name Schema

access_key
optional

string

last_used
optional

string (date-time)

auth.credentials

Name Description Schema

access_key
optional

Credentials access key

string

secret_key
optional

Credentials secret key

string

auth.role

Type : enum (admin, superuser, user, annotator)

events.event_type_enum

Type : enum (training_stats_scalar, training_stats_vector, training_debug_image, plot, log)

events.log_level_enum

Type : enum (notset, debug, verbose, info, warn, warning, error, fatal, critical)

events.metrics_image_event

An image or video was dumped to storage for debugging

Name Description Schema

iter
optional

Iteration

integer

key
optional

File key

string

metric
optional

Metric name, e.g. 'count', 'loss', 'accuracy'

string

task
required

Task ID (required)

string

timestamp
optional

Epoch milliseconds UTC, will be set by the server if not set.

number

url
optional

File URL

string

variant
optional

E.g. 'class_1', 'total', 'average

string

events.metrics_plot_event

An entire plot (not single datapoint) and it’s layout. Used for plotting ROC curves, confidence matrices, etc. when evaluating the net.

Name Description Schema

iter
optional

Iteration

integer

metric
optional

Metric name, e.g. 'count', 'loss', 'accuracy'

string

plot_str
optional

An entire plot (not single datapoint) and it’s layout. Used for plotting ROC curves, confidence matrices, etc. when evaluating the net.

string

task
required

Task ID (required)

string

timestamp
optional

Epoch milliseconds UTC, will be set by the server if not set.

number

variant
optional

E.g. 'class_1', 'total', 'average

string

events.metrics_scalar_event

Used for reporting scalar metrics during training task

Name Description Schema

iter
optional

Iteration

integer

metric
optional

Metric name, e.g. 'count', 'loss', 'accuracy'

string

task
required

Task ID (required)

string

timestamp
optional

Epoch milliseconds UTC, will be set by the server if not set.

number

value
optional

number

variant
optional

E.g. 'class_1', 'total', 'average

string

events.metrics_vector_event

Used for reporting vector metrics during training task

Name Description Schema

iter
optional

Iteration

integer

metric
optional

Metric name, e.g. 'count', 'loss', 'accuracy'

string

task
required

Task ID (required)

string

timestamp
optional

Epoch milliseconds UTC, will be set by the server if not set.

number

values
optional

vector of float values

< number > array

variant
optional

E.g. 'class_1', 'total', 'average

string

events.scalar_key_enum

Type : enum (iter, timestamp, iso_time)

events.task_log_event

A log event associated with a task.

Name Description Schema

level
optional

Log level.

events.log_level_enum

msg
optional

Log message.

string

task
required

Task ID (required)

string

timestamp
optional

Epoch milliseconds UTC, will be set by the server if not set.

number

worker
optional

Name of machine running the task.

string

events.task_metric

Name Description Schema

metric
required

Metric name

string

task
required

Task ID

string

models.model

Name Description Schema

comment
optional

Model comment

string

company
optional

Company id

string

created
optional

Model creation time

string (date-time)

design
optional

Json object representing the model design. Should be identical to the network design of the task which created the model

object

framework
optional

Framework on which the model is based. Should be identical to the framework of the task which created the model

string

id
optional

Model id

string

labels
optional

Json object representing the ids of the labels in the model. The keys are the layers' names and the values are the ids.

< string, integer > map

name
optional

Model name

string

parent
optional

Parent model ID

string

project
optional

Associated project ID

string

ready
optional

Indication if the model is final and can be used by other tasks

boolean

system_tags
optional

System tags. This field is reserved for system use, please don’t use it.

< string > array

tags
optional

User-defined tags

< string > array

task
optional

Task ID of task in which the model was created

string

ui_cache
optional

UI cache for this model

object

uri
optional

URI for the model, pointing to the destination storage.

string

user
optional

Associated user id

string

models.multi_field_pattern_data

Name Description Schema

fields
optional

List of field names

< string > array

pattern
optional

Pattern string (regex)

string

projects.metric_variant_result

Name Description Schema

metric
optional

Metric name

string

metric_hash
optional

Metric name hash. Used instead of the metric name when categorizing last metrics events in task objects.

string

variant
optional

Variant name

string

variant_hash
optional

Variant name hash. Used instead of the variant name when categorizing last metrics events in task objects.

string

projects.multi_field_pattern_data

Name Description Schema

fields
optional

List of field names

< string > array

pattern
optional

Pattern string (regex)

string

projects.project

Name Description Schema

company
optional

Company id

string

created
optional

Creation time

string (date-time)

default_output_destination
optional

The default output destination URL for new tasks under this project

string

description
optional

Project description

string

id
optional

Project id

string

last_update
optional

Last project update time. Reflects the last time the project metadata was changed or a task in this project has changed status

string (date-time)

name
optional

Project name

string

system_tags
optional

System tags. This field is reserved for system use, please don’t use it.

< string > array

tags
optional

User-defined tags

< string > array

user
optional

Associated user id

string

projects.projects_get_all_response_single

Name Description Schema

company
optional

Company id

string

created
optional

Creation time

string (date-time)

default_output_destination
optional

The default output destination URL for new tasks under this project

string

description
optional

Project description

string

id
optional

Project id

string

name
optional

Project name

string

stats
optional

Additional project stats

projects.stats

system_tags
optional

System tags. This field is reserved for system use, please don’t use it.

< string > array

tags
optional

User-defined tags

< string > array

user
optional

Associated user id

string

projects.stats

Name Description Schema

active
optional

Stats for active tasks

projects.stats_status_count

archived
optional

Stats for archived tasks

projects.stats_status_count

projects.stats_status_count

Name Description Schema

status_count
optional

Status counts

status_count

total_runtime
optional

Total run time of all tasks in project (in seconds)

integer

status_count

Name Description Schema

closed
optional

Number of 'closed' tasks in project

integer

created
optional

Number of 'created' tasks in project

integer

failed
optional

Number of 'failed' tasks in project

integer

in_progress
optional

Number of 'in_progress' tasks in project

integer

published
optional

Number of 'published' tasks in project

integer

queued
optional

Number of 'queued' tasks in project

integer

stopped
optional

Number of 'stopped' tasks in project

integer

unknown
optional

Number of 'unknown' tasks in project

integer

queues.entry

Name Description Schema

added
optional

Time this entry was added to the queue

string (date-time)

task
optional

Queued task ID

string

queues.queue

Name Description Schema

company
optional

Company id

string

created
optional

Queue creation time

string (date-time)

entries
optional

List of ordered queue entries

< queues.entry > array

id
optional

Queue id

string

name
optional

Queue name

string

system_tags
optional

System tags. This field is reserved for system use, please don’t use it.

< string > array

tags
optional

User-defined tags

< string > array

user
optional

Associated user id

string

queues.queue_metrics

Name Description Schema

avg_waiting_times
optional

List of average waiting times for tasks in the queue. The points correspond to the timestamps in the dates list. If more than one value exists for the given interval then the maximum value is taken.

< number > array

dates
optional

List of timestamps (in seconds from epoch) in the acceding order. The timestamps are separated by the requested interval. Timestamps where no queue status change was recorded are omitted.

< integer > array

queue
optional

ID of the queue

string

queue_lengths
optional

List of tasks counts in the queue. The points correspond to the timestamps in the dates list. If more than one value exists for the given interval then the count that corresponds to the maximum average value is taken.

< integer > array

tasks.artifact

Name Description Schema

content_size
optional

Raw data length in bytes

integer

display_data
optional

User-defined list of key/value pairs, sorted

< < string > array > array

hash
optional

Hash of entire raw data

string

key
required

Entry key

string

mode
optional

System defined input/output indication
Default : "output"

enum (input, output)

timestamp
optional

Epoch time when artifact was created

integer

type
required

System defined type

string

type_data
optional

Additional fields defined by the system

tasks.artifact_type_data

uri
optional

Raw data location

string

tasks.artifact_type_data

Name Description Schema

content_type
optional

System defined raw data content type

string

data_hash
optional

Hash of raw data, without any headers or descriptive parts

string

preview
optional

Description or textual data

string

tasks.configuration_item

Name Description Schema

description
optional

The parameter description. Optional

string

name
optional

Name of the parameter. Should be unique

string

type
optional

Type of the parameter. Optional

string

value
optional

Value of the parameter

string

tasks.execution

Name Description Schema

artifacts
optional

Task artifacts

< tasks.artifact > array

docker_cmd
optional

Command for running docker script for the execution of the task

string

framework
optional

Framework related to the task. Case insensitive. Mandatory for Training tasks.

string

model
optional

Execution input model ID Not applicable for Register (Import) tasks

string

model_desc
optional

Json object representing the Model descriptors

object

model_labels
optional

Json object representing the ids of the labels in the model. The keys are the layers' names and the values are the IDs. Not applicable for Register (Import) tasks. Mandatory for Training tasks

< string, integer > map

parameters
optional

Json object containing the Task parameters

object

queue
optional

Queue ID where task was queued.

string

tasks.last_metrics_event

Name Description Schema

max_value
optional

Maximum value reported

number

metric
optional

Metric name

string

min_value
optional

Minimum value reported

number

value
optional

Last value reported

number

variant
optional

Variant name

string

tasks.last_metrics_variants

Last metric events, one for each variant hash

Type : < string, tasks.last_metrics_event > map

tasks.multi_field_pattern_data

Name Description Schema

fields
optional

List of field names

< string > array

pattern
optional

Pattern string (regex)

string

tasks.output

Name Description Schema

destination
optional

Storage id. This is where output files will be stored.

string

error
optional

Last error text

string

model
optional

Model id.

string

result
optional

Task result. Values: 'success', 'failure'

string

tasks.param_key

Name Description Schema

name
optional

Name of the parameter. If the name is ommitted then the corresponding operation is performed on the whole section

string

section
optional

Section that the parameter belongs to

string

tasks.params_item

Name Description Schema

description
optional

The parameter description. Optional

string

name
optional

Name of the parameter. The combination of section and name should be unique

string

section
optional

Section that the parameter belongs to

string

type
optional

Type of the parameter. Optional

string

value
optional

Value of the parameter

string

tasks.replace_hyperparams_enum

Type : enum (none, section, all)

tasks.script

Name Description Schema

binary
optional

Binary to use when running the script
Default : "python"

string

branch
optional

Repository branch id If not provided and tag not provided, default repository branch is used.

string

diff
optional

Uncommitted changes found in the repository when task was run

string

entry_point
optional

Path to execute within the repository

string

repository
optional

Name of the repository where the script is located

string

requirements
optional

A JSON object containing requirements strings by key

object

tag
optional

Repository tag

string

version_num
optional

Version (changeset) number. Optional (default is head version) Unused if tag is provided.

string

working_dir
optional

Path to the folder from which to run the script Default - root folder of repository

string

tasks.section_params

Task section params

Type : < string, tasks.params_item > map

tasks.task

Name Description Schema

comment
optional

Free text comment

string

company
optional

Company ID

string

completed
optional

Task end time (UTC)

string (date-time)

configuration
optional

Task configuration params

< string, tasks.configuration_item > map

created
optional

Task creation time (UTC)

string (date-time)

execution
optional

Task execution params

tasks.execution

hyperparams
optional

Task hyper params per section

< string, tasks.section_params > map

id
optional

Task id

string

last_iteration
optional

Last iteration reported for this task

integer

last_metrics
optional

Last metric variants (hash to events), one for each metric hash

< string, tasks.last_metrics_variants > map

last_update
optional

Last time this task was created, updated, changed or events for this task were reported

string (date-time)

last_worker
optional

ID of last worker that handled the task

string

last_worker_report
optional

Last time a worker reported while working on this task

string (date-time)

name
optional

Task Name

string

output
optional

Task output params

tasks.output

parent
optional

Parent task id

string

project
optional

Project ID of the project to which this task is assigned

string

published
optional

Last status change time

string (date-time)

script
optional

Script info

tasks.script

started
optional

Task start time (UTC)

string (date-time)

status
optional

tasks.task_status_enum

status_changed
optional

Last status change time

string (date-time)

status_message
optional

free text string representing info about the status

string

status_reason
optional

Reason for last status change

string

system_tags
optional

System tags list. This field is reserved for system use, please don’t use it.

< string > array

tags
optional

User-defined tags list

< string > array

type
optional

Type of task. Values: 'training', 'testing'

tasks.task_type_enum

user
optional

Associated user id

string

tasks.task_status_enum

Type : enum (created, queued, in_progress, stopped, published, publishing, closed, failed, completed, unknown)

tasks.task_type_enum

Type : enum (training, testing, inference, data_processing, application, monitor, controller, optimizer, service, qc, custom)

users.get_current_user_response_user_object

like user, but returns company object instead of ID

Name Description Schema

avatar
optional

string

company
optional

company

family_name
optional

string

given_name
optional

string

id
optional

string

name
optional

string

preferences
optional

User preferences

object

role
optional

string

company

Name Schema

id
optional

string

name
optional

string

users.user

Name Description Schema

avatar
optional

Avatar URL

string

company
optional

Company ID

string

created
optional

User creation date

string (date-time)

email
optional

User email

string (email)

family_name
optional

Family name

string

given_name
optional

Given name

string

id
optional

User ID

string

name
optional

Full name

string

providers
optional

Providers uses has logged-in with

object

role
optional

User’s role (admin only)

string

workers.activity_series

Name Description Schema

counts
optional

List of worker counts corresponding to the timestamps in the dates list. None values are returned for the dates with no workers.

< integer > array

dates
optional

List of timestamps (in seconds from epoch) in the acceding order. The timestamps are separated by the requested interval.

< integer > array

workers.aggregation_stats

Name Description Schema

aggregation
optional

workers.aggregation_type

values
optional

List of values corresponding to the dates in metric statistics

< number > array

workers.aggregation_type

Metric aggregation type

Type : enum (avg, min, max)

workers.current_task_entry

Name Description Schema

id
optional

ID

string

last_iteration
optional

Last task iteration

integer

name
optional

Name

string

running_time
optional

Task running time

integer

workers.id_name_entry

Name Description Schema

id
optional

ID

string

name
optional

Name

string

workers.machine_stats

Name Description Schema

cpu_temperature
optional

CPU temperature

< number > array

cpu_usage
optional

Average CPU usage per core

< number > array

disk_free_home
optional

Mbytes free space of /home drive

integer

disk_free_temp
optional

Mbytes free space of /tmp drive

integer

disk_read
optional

Mbytes read per second

integer

disk_write
optional

Mbytes write per second

integer

gpu_memory_free
optional

GPU free memory MBs

< integer > array

gpu_memory_used
optional

GPU used memory MBs

< integer > array

gpu_temperature
optional

GPU temperature

< number > array

gpu_usage
optional

Average GPU usage per GPU card

< number > array

memory_free
optional

Free memory MBs

integer

memory_used
optional

Used memory MBs

integer

network_rx
optional

Mbytes per second

integer

network_tx
optional

Mbytes per second

integer

workers.metric_stats

Name Description Schema

dates
optional

List of timestamps (in seconds from epoch) in the acceding order. The timestamps are separated by the requested interval. Timestamps where no workers activity was recorded are omitted.

< integer > array

metric
optional

Name of the metric (cpu_usage, memory_used etc.)

string

stats
optional

Statistics data by type

< workers.aggregation_stats > array

variant
optional

Name of the metric component. Set only if 'split_by_variant' was set in the request

string

workers.metrics_category

Name Description Schema

metric_keys
optional

The names of the metrics in the category.

< string > array

name
optional

Name of the metrics category.

string

workers.queue_entry

Name Description Schema

id
optional

ID

string

name
optional

Name

string

next_task
optional

Next task in the queue

workers.id_name_entry

num_tasks
optional

Number of task entries in the queue

integer

workers.stat_item

Name Description Schema

category
optional

workers.aggregation_type

key
optional

Name of a metric

string

workers.worker

Name Description Schema

company
optional

Associated company

workers.id_name_entry

id
optional

Worker ID

string

ip
optional

IP of the worker

string

last_activity_time
optional

Last activity time (even if an error occurred)

string (date-time)

last_report_time
optional

Last successful report time

string (date-time)

project
optional

Project in which currently executing task resides

workers.id_name_entry

queue
optional

Queue from which running task was taken

workers.queue_entry

queues
optional

List of queues on which the worker is listening

< workers.queue_entry > array

register_time
optional

Registration time

string (date-time)

tags
optional

User tags for the worker

< string > array

task
optional

Task currently being run by the worker

workers.current_task_entry

user
optional

Associated user (under whose credentials are used by the worker daemon)

workers.id_name_entry

workers.worker_stats

Name Description Schema

metrics
optional

List of the metrics statistics for the worker

< workers.metric_stats > array

worker
optional

ID of the worker

string