Skip to main content

Jobs and takes

Jobs and takes are the core concepts that power the Move API workflow. Understanding these concepts is essential for building effective motion capture applications.

What is a job?​

A job is a processing task that converts video input into motion capture data. Think of it as a "work order" that tells the Move API what to process and how to process it.

Job lifecycle​

Every job follows this lifecycle:

  1. Not started - Job is submitted with video files and parameters
  2. Running - AI models are analyzing the video
  3. Completed - Processing finished, take is ready
  4. Failed - Processing encountered an error

Job properties​

Each job contains:

{
    "data": {
        "getJob": {
            "id": "job-813c4746-ac97-4342-abf0-83fce3ba4c40",
            "name": "",
            "progress": {
                "state": "FINISHED",
                "percentageComplete": 100
            },
            "inputs": {
                "options": {
                    "mocapModel": "S1",
                    "trackBall": false,
                    "trackFingers": true
                },
                "numberOfActors": 1
            },
            "outputs": [
                {
                    "key": "mp4",
                    "file": {
                        "id": "file-bac9b556-15b7-45db-96cf-32cdb39e8714",
                        "presignedUrl": "https://moveai-file-storage-production.s3-accelerate.amazonaws.com/outputs/bac9b556-15b7-45db-96cf-32cdb39e8714.mp4?AWSAccessKeyId=xxxxxxxxxxxxxxx&Signature=xxxxxxxxxxxxxxxxxxxxxxxxxxx&x-amz-security-token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxExpires=1755860861",
                        "created": "2025-08-22T10:07:41.325122Z"
                    }
                },
                {
                    "key": "usdz",
                    "file": {
                        "id": "file-6bf1e4f5-caaa-4a8f-874c-95fbce92cac8",
                        "presignedUrl": "https://moveai-file-storage-production.s3-accelerate.amazonaws.com/outputs/6bf1e4f5-caaa-4a8f-874c-95fbce92cac8.usdz?AWSAccessKeyId=xxxxxxxxxxxxxxx&Signature=xxxxxxxxxxxxxxxxxxxxxxxxxxx&x-amz-security-token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxExpires=1755860861",
                    }
                },
                {
                    "key": "render_overlay_mp4",
                    "file": {
                        "id": "file-f6bfa6a2-77c2-4c08-949b-47f13acdfb0f",
                        "presignedUrl": "https://moveai-file-storage-production.s3-accelerate.amazonaws.com/outputs/f6bfa6a2-77c2-4c08-949b-47f13acdfb0f.mp4?AWSAccessKeyId=xxxxxxxxxxxxxxx&Signature=xxxxxxxxxxxxxxxxxxxxxxxxxxx&x-amz-security-token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxExpires=1755860861",
                        "created": "2025-08-22T10:07:41.337707Z"
                    }
                },
                {
                    "key": "blend",
                    "file": {
                        "id": "file-90e0b7e0-a83f-4464-9af1-7a3536b64434",
                        "presignedUrl": "https://moveai-file-storage-production.s3-accelerate.amazonaws.com/outputs/90e0b7e0-a83f-4464-9af1-7a3536b64434.blend?AWSAccessKeyId=xxxxxxxxxxxxxxx&Signature=xxxxxxxxxxxxxxxxxxxxxxxxxxx&x-amz-security-token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxExpires=1755860861",
                        "created": "2025-08-22T10:07:41.371268Z"
                    }
                },
                {
                    "key": "usdc",
                    "file": {
                        "id": "file-fe3d0f91-c104-45be-b8f9-e5d788ae2569",
                        "presignedUrl": "https://moveai-file-storage-production.s3-accelerate.amazonaws.com/outputs/fe3d0f91-c104-45be-b8f9-e5d788ae2569.usdc?AWSAccessKeyId=xxxxxxxxxxxxxxx&Signature=xxxxxxxxxxxxxxxxxxxxxxxxxxx&x-amz-security-token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxExpires=1755860861",
                        "created": "2025-08-22T10:07:41.337955Z"
                    }
                },
                {
                    "key": "motion_data",
                    "file": {
                        "id": "file-660a28b2-ffd8-4ccf-9370-c23620ae100d",
                        "presignedUrl": "https://moveai-file-storage-production.s3-accelerate.amazonaws.com/outputs/660a28b2-ffd8-4ccf-9370-c23620ae100d.zip?AWSAccessKeyId=xxxxxxxxxxxxxxx&Signature=xxxxxxxxxxxxxxxxxxxxxxxxxxx&x-amz-security-token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxExpires=1755860861",
                        "created": "2025-08-22T10:07:41.438225Z"
                    }
                },
                {
                    "key": "fbx",
                    "file": {
                        "id": "file-86700915-528f-4b78-80b6-890e1216d69b",
                        "presignedUrl": "https://moveai-file-storage-production.s3-accelerate.amazonaws.com/outputs/86700915-528f-4b78-80b6-890e1216d69b.fbx?AWSAccessKeyId=xxxxxxxxxxxxxxx&Signature=xxxxxxxxxxxxxxxxxxxxxxxxxxx&x-amz-security-token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxExpires=1755860861",
                        "created": "2025-08-22T10:07:41.358880Z"
                    }
                }
            ]
        }
    }
}

What is a take?​

Takes are a way to define a recording session. A single take can be associated with one or more video file. A take can be used as an input to multiple jobs

A take includes:

  • Sources: A grouping of a video file and file type associated with the take.

Take properties​

{
    "data": {
        "take": {
            "id": "take-97065110-6a0e-4c37-8904-f4f4c4adb242",
            "sources": [
                {
                    "deviceLabel": "cam01",
                    "file": {
                        "id": "file-e07e5bad-6ae2-42e7-84c1-20dedf9b923c"
                    },
                    "format": "MP4"
                }
            ]
        }
    }
}

Working with jobs​

Creating a job​

  ugc.jobs.create_create_singlecamjob(take_id="<TAKE ID FROM TAKE CREATION">)

Monitoring job status​

# Check job status
job = client.jobs.retrieve(id="<JOB ID>")

if job.state == "COMPLETED":
    print("Job completed! Take ready for download.")
elif job.state == "FAILED":
    print("Job still processing...")
elif job.state == "failed":
    print(f"Job failed: {job.error_message}")

Polling for completion​

import time

while True:
    job = client.jobs.retrieve(id="<JOB ID>")
    
    if job.state == "FINISHED":
        print("Job completed!")
        break
    elif job.state == "FAILED":
        print(f"Job failed: {job.error_message}")
        break
    
    print("Still processing...")
    time.sleep(10)  # Wait 10 seconds before checking again
tip

We recommend using events from webhooks than polling for the status of the job

Working with takes​

Creating a take​

  file_id="<FILE ID FROM FILE CREATION>"

  #Create a take with the file id
  ugc.takes.create(file_id=file_id)

Listing takes​

query ListTakes {
    listTakes {
        after
        first
        items {
            created
            id
            metadata
            name
            takeType
            sources {
                deviceLabel
                format
                cameraSettings {
                    lens
                }
            }
        }
    }
}

Take and job relationships​

  • One-to-Many: Each take can be used in multiple jobs
  • Take ID: Every completed take has a take_id
  • Job ID: Every job has a job_id that references its source take_id

Best practices​

Job management​

  • Monitor Status: Always check job status before proceeding
  • Handle Errors: Implement error handling for failed jobs
  • Polling: Use reasonable intervals when polling for completion, use webhooks wherever possible
  • Specify Outputs: Specify the outputs formats required

Next steps​