Request

Response

    Create a new job
    POST

    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
    * Required

    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

    Expand all
    entitlement
    string
    Name of an entitlement to use certain capabilities
    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
    This feature is experimental.
    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. This specifies the inputs to be downloaded before the task starts.
    source*
    one of
    Represents an external storage location, either a URI or a reference to 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 storage space, specified as <storage provider>:<storage space key>.
    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 than 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.

    packages
    object
    Specifies the set of packages that are required by the task
    *
    one of
    Package specification
    one of
    Specifies which version of a package to use
    Package version
    string
    A specific version of a package.

    Max length: 200

    Package version
    enum:string
    Constants for package versions Will always be: *
    Package details
    object
    Detailed specification for a package
    version
    one of
    Specifies which version of a package to use
    Package version
    string
    A specific version of a package.

    Max length: 200

    Package version
    enum:string
    Constants for package versions Will always be: *
    variant
    object
    Specifies any variant for a package
    *
    string
    Selects a specific variant

    Max length: 200

    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. This specifies the inputs to be downloaded before the task starts.
    source*
    one of
    Represents an external storage location, either a URI or a reference to 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 storage space, specified as <storage provider>:<storage space key>.
    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 than 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.

    packages
    object
    Specifies the set of packages that are required by the task
    *
    one of
    Package specification
    one of
    Specifies which version of a package to use
    Package version
    string
    A specific version of a package.

    Max length: 200

    Package version
    enum:string
    Constants for package versions Will always be: *
    Package details
    object
    Detailed specification for a package
    version
    one of
    Specifies which version of a package to use
    Package version
    string
    A specific version of a package.

    Max length: 200

    Package version
    enum:string
    Constants for package versions Will always be: *
    variant
    object
    Specifies any variant for a package
    *
    string
    Selects a specific variant

    Max length: 200

    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.
    * Required

    Response

    HTTP Status Code Summary

    201
    Created
    Created
    400
    Bad Request
    Bad request - indicates an incorrectly structured 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)

    Expand all
    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 creates a job to scatter trees on a plane using the bifrost executor. For this to work, it requires 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
                }
            }
        ]
    }'
    
    Show More

    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"
    }
    
    Show More