This is the API v2 documentation. API v2 is currently in preview state and not recommended for production use! Read more about API v2 in our blog post.

Socket API

The CloudConvert Socket API offers real time task updates. We use the Socket.io protocol. Socket.io clients are available in JavaScript and other languages. The official Node SDK has a built in handling for the Websocket API. The Socket.io base host is https://socketio.cloudconvert.com. When joining channels you need to authorize using the Authorization: Bearer API_KEY header (see example below).

Channels and Events

Channel Description Available Events
private-job.{jobId} Events for a specific job. job.created
job.updated
job.finished
job.failed
private-task.{taskId} Events for a specific task. task.created
task.updated
task.finished
task.failed
private-job.{jobId}.tasks All task events for a specific job. task.created
task.updated
task.finished
task.failed
private-user.{userId}.tasks All task events for your user. You can find out your user id using the users/me endpoint. task.created
task.updated
task.finished
task.failed
private-user.{userId}.jobs All job events for your user. You can find out your user id using the users/me endpoint. job.created
job.updated
job.finished
job.failed

Example

The following example shows how to listen for the task.created and task.finished event using the Socket.io JavaScript client.

const socket = io.connect('https://socketio.cloudconvert.com');

socket.emit('subscribe', {
    channel: 'private-jobs.6559c281-ed85-4728-80db-414561c631e9.tasks',
    auth: {
        headers: {
            Authorization: 'Bearer API_KEY'
        }
    },
});

socket.on('task.created', function (channel, data) {
    console.log(data.task);
});

socket.on('task.finished', function (channel, data) {
    console.log(data.task);
});