queues/{queueId}/jobs
Creates a new job in the queue specified by queueId. The description of the job specified in the request body consists of a combination of the generic structure given here and executor-specific parts. In particular the payload property contains executor specific data. For the specifics there refer to the executor schema definition. This endpoint expects an OAuth2 bearer token with code:all scope.
Resource Information
Method and URI | POST https://developer.api.autodesk.com/flow/compute/v1/queues/{queueId}/jobs |
Authentication Context | user context optional |
Required OAuth Scopes | code:all |
Data Format | JSON |
Request
Headers
Authorization* string | Must be Bearer <token> , where <token> is obtained via either a two-legged or three-legged OAuth flow. |
region string | The region targeted by the request. The usage of this header is recommended for faster processing. The region specified must match the region in which the targeted job queue was created or else the request will fail. |
Content-Type* string | Must be application/json |
Request
URI Parameters
queueId string | The queue ID. Use the special ID @default to indicate the default queue for the user or client app. |
Request
Body Structure
name string | The user-provided name of the job.
Max length: 200 |
tags array: string | A list of user-provided tags |
tasks array | |
oneOf array:oneOf | |
MapTask specialization object | |
name string | The name of a task. Task names are unique within a job
Max length: 1000 |
type* enum:string | Will always be: map |
task* object | A description of the task to be performed. |
name string | The name of a task. Task names are unique within a job
Max length: 1000 |
type enum:string | Will always be: task |
executor one of | A reference to the task executor that should perform a specific task, indicating which compute capability should perform the task. |
Task executor name string | The name of a task executor
Max length: 200 |
Task executor version reference object | References a specific task executor version |
name* string | The name of a task executor
Max length: 200 |
version string | The version of a task executor
Max length: 200 |
hints object | Optional hints to be provided to the task executor, that may be taken into account when performing the task. |
inputs array: object | A list of input resources needed by the task. |
source* one of | Represents an external storage location, either a URI or a reference info a storage space. |
URI storage location* object | A URI where a particular resource is located. |
uri* string | The resource URI |
Space storage location* object | Represents a storage location within a specific storage space |
key* string | The unique key within the storage space that refers to the particular object within the space. |
spaceId* string | An ID for a specific storage space, unique within the job |
target object | Describes how a resource is mapped to a local view, e.g. a file path where the resource should be placed or found. |
path string | A file system path referring to a location on disk. File system paths are always interpreted as Posix style and will always be transformed into relative paths. This includes them being case sensitive, and in addition control characters are not permitted.
Max length: 4000 |
limitations object | Specifies optional limitations for the task. |
maxExecutionTimeInSeconds int | Max execution time for the task, specified in seconds. The service will attempt to limit the task to run for no longer that this. Can be set to up to 172800 seconds (2 days).
Note: Additional limitations may apply, meaning that a task may be canceled prior to reaching this limit. |
payload object | Executor-specific information used to instruct the executor on what to do. For more information see the executor documentation. |
requirements object | Specifies requirements for the task. The service will attempt to ensure that these requirements are met, but for instance some resources may be devoted to task management and similar. Also, the service may elect to run the task with a different resource allocation, meaning that the actual amount of memory or CPU available to the task may differ from these requirements. |
cpu int | The minimum number of vCPUs that should be allocated to run the task. The maximum number may differ depending on the executor as well as other configuration, but it can currently never exceed 16 vCPUs. If the minimum vCPU count given cannot be satisfied the task will fail with an error. |
memory int | The minimum amount of memory needed to run the task, specified in MBs. The maximum allowed amount of memory may differ depending on executor as well as other configuration, but can currently never exceed 122880 MBs. If the minimum amount of memory specified cannot be satisfied the task will fail with an error. |
values* object | |
source* string | |
TaskDescription specialization object | A description of the task to be performed. |
name string | The name of a task. Task names are unique within a job
Max length: 1000 |
type enum:string | Will always be: task |
executor one of | A reference to the task executor that should perform a specific task, indicating which compute capability should perform the task. |
Task executor name string | The name of a task executor
Max length: 200 |
Task executor version reference object | References a specific task executor version |
name* string | The name of a task executor
Max length: 200 |
version string | The version of a task executor
Max length: 200 |
hints object | Optional hints to be provided to the task executor, that may be taken into account when performing the task. |
inputs array: object | A list of input resources needed by the task. |
source* one of | Represents an external storage location, either a URI or a reference info a storage space. |
URI storage location* object | A URI where a particular resource is located. |
uri* string | The resource URI |
Space storage location* object | Represents a storage location within a specific storage space |
key* string | The unique key within the storage space that refers to the particular object within the space. |
spaceId* string | An ID for a specific storage space, unique within the job |
target object | Describes how a resource is mapped to a local view, e.g. a file path where the resource should be placed or found. |
path string | A file system path referring to a location on disk. File system paths are always interpreted as Posix style and will always be transformed into relative paths. This includes them being case sensitive, and in addition control characters are not permitted.
Max length: 4000 |
limitations object | Specifies optional limitations for the task. |
maxExecutionTimeInSeconds int | Max execution time for the task, specified in seconds. The service will attempt to limit the task to run for no longer that this. Can be set to up to 172800 seconds (2 days).
Note: Additional limitations may apply, meaning that a task may be canceled prior to reaching this limit. |
payload object | Executor-specific information used to instruct the executor on what to do. For more information see the executor documentation. |
requirements object | Specifies requirements for the task. The service will attempt to ensure that these requirements are met, but for instance some resources may be devoted to task management and similar. Also, the service may elect to run the task with a different resource allocation, meaning that the actual amount of memory or CPU available to the task may differ from these requirements. |
cpu int | The minimum number of vCPUs that should be allocated to run the task. The maximum number may differ depending on the executor as well as other configuration, but it can currently never exceed 16 vCPUs. If the minimum vCPU count given cannot be satisfied the task will fail with an error. |
memory int | The minimum amount of memory needed to run the task, specified in MBs. The maximum allowed amount of memory may differ depending on executor as well as other configuration, but can currently never exceed 122880 MBs. If the minimum amount of memory specified cannot be satisfied the task will fail with an error. |
Response
HTTP Status Code Summary
201 Created | Created |
400 Bad Request | Bad request - indicates an incorrectly structure or otherwise incorrect request. |
401 Unauthorized | Unauthorized - credentials are invalid or not provided in the request |
403 Forbidden | Forbidden - the user or client does not have the required privileges to access this resource |
Response
Body Structure (201)
createdAt datetime: ISO 8601 | The date and time of creation in ISO 8601 format (UTC) |
updatedAt datetime: ISO 8601 | The date and time of the last update in ISO 8601 format (UTC) |
startedAt datetime: ISO 8601 | The date and time when processing started in ISO 8601 format (UTC) |
endedAt datetime: ISO 8601 | The date and time when processing completed in ISO 8601 format (UTC) |
error object | Information about an error encountered while executing a task |
details object | |
message string | A text representation of the error. |
id string | A unique ID for a specific job
Max length: 1024 |
name string | The user-provided name of the job.
Max length: 200 |
progress object | Provides information about the progress of a task. |
percent number | Indicates the percentage complete for a task.
Note: The percentage complete is an indication only and should not be used to determine whether a task is entirely completed or not - use the status for this instead. |
details object | Executor-specific additional progress details. |
stats object | |
tasks object | Statistics relating to the number of task executions in a job or within a task execution that can result in multiple task executions. |
canceled int | The number of canceled task executions currently known. |
failed int | The number of failed task executions currently known. |
running int | The number of running task executions currently known. |
scheduled int | The number of scheduled task executions currently known. |
succeeded int | The number of succeeded task executions currently known. |
total int | The total number of task executions currently known. |
waiting int | The number of waiting task executions currently known. |
results object | The results from a task. |
details object | Executor-specific task result details. |
status enum:string | Specifies the status of a task/job
Possible values: CREATED , WAITING , SCHEDULED , RUNNING , SUCCEEDED , FAILED , CANCELED |
tags array: string | A list of user-provided tags |
Example
This example create a job to scatter trees on a plane using the bifrost executor. For this to work, it require the graph and input file to have been uploaded pior to submitting the job. For an example see, our sample code here.
Request
curl -v 'https://developer.api.autodesk.com/flow/compute/v1/queues/@default/jobs' \
-X 'POST' \
-H 'Authorization: Bearer eyJhbGc...' \
-H 'Content-Type: application/json'\
-d '{
"name": "my sample app job",
"tags": [
"sample app"
],
"tasks": [
{
"name": "execute bifrost graph",
"type": "task",
"executor": "bifrost",
"inputs": [],
"limitations": {
"maxExecutionTimeInSeconds": 600
},
"payload": {
"action": "Evaluate",
"options": {
"compound": "User::Graphs::addTrees",
"frames": {
"start": 1,
"end": 1
}
},
"definitionFiles": [
{
"source": {
"uri": "urn:adsk:fc.scratch:us-west.prd:resource:@default/bifrostGraph.json"
},
"target": {
"path": "bifrostgraph.json"
}
}
],
"ports": {
"inputPorts": [
{
"name": "inputFilename",
"value": "plane.usd",
"type": "string"
},
{
"name": "outputFilename",
"value": "planeWithTrees.usd",
"type": "string"
},
{
"name": "amount",
"value": "1000",
"type": "float"
}
],
"jobPorts": []
},
"executions": [
{
"inputs": [
{
"source": {
"uri": "urn:adsk:fc.scratch:us-west.prd:resource:@default/plane.usd"
},
"target": {
"path": "plane.usd"
}
}
],
"outputs": [
{
"source": {
"path": "planeWithTrees.usd"
},
"target": {
"name": "planeWithTrees.usd"
}
}
],
"frameId": 1
}
]
},
"requirements": {
"cpu": 4,
"memory": 30720
}
}
]
}'
Response
{
"createdAt": "0001-01-01T00:00:00.000Z",
"id": "8167aec1-c057-423a-8256-5b5883477d91",
"name": "my sample app job",
"progress": {
"percent": 0,
"details": {
"stats": {
"tasks": {
"scheduled": 1,
"total": 1
}
}
}
},
"status": "SCHEDULED",
"tags": [
"sample app"
],
"updatedAt": "0001-01-01T00:00:00.000Z"
}