This article explains how to use the Supplier Data Manager (SDM) REST API to track the progress of a job, list jobs in your organization, cancel a job, and retrieve job output data in JSON format.

All requests require an Authorization: Token <YOUR_TOKEN> header. For authentication setup, see Getting started with the API.

Get the status of an SDM job

To check the current status of a Supplier Data Manager job, call the job detail endpoint:

GET https://sdm.akeneo.cloud/api/v1/jobs/{job_id}/

Replace {job_id} with the UUID returned when the job was created.

The response includes a status field with one of the following values:

Example response:

{
    "status": "running",
    "step": {
        "id": 1
    }
}

When status is error, the message field in the response contains a description of the failure.

Note: After a step is validated, the job can stay pending on that step for a short time while SDM saves the step results. The job is then not waiting for you. To know if SDM is still working, use the progress endpoint below.

Follow the progress of an SDM job

To see each step of a job and where the current step stands, call the job progress endpoint:

GET https://sdm.akeneo.cloud/api/v1/jobs/{job_id}/progress/

Among other fields, the response includes a status field for the job and a steps list:

Note: This endpoint uses in_progress and completed where the job status endpoint uses running and done. When a validated step still saves its results, this endpoint reports in_progress, and the job status endpoint reports pending.

While SDM works on the current step, the entry of that step in steps also has these fields:

These fields are present only if your access includes the current step. For example, a supplier portal sees them only for the steps up to its last accessible step.

To count the products of a step, use processed_products and total_products. The progress, progress_current and progress_total fields of a step come from an internal task and do not count products.

Example response (extract):

{
    "status": "in_progress",
    "steps": [
        {
            "name": "Mapping",
            "status": "in_progress",
            "phase": "processing",
            "processed_products": 1000,
            "total_products": 3000
        },
        {
            "name": "Extraction",
            "status": "not_started"
        }
    ]
}

Retrieve the list of SDM jobs

To retrieve all jobs created in your organization, call:

GET https://sdm.akeneo.cloud/api/v1/jobs/

Filter parameters

Narrow results by adding query parameters:

Example — all completed jobs for project 17 created after 1 January 2022:

GET https://sdm.akeneo.cloud/api/v1/jobs/?status=done&project=17&created_after=2022-01-01T00:00:00Z

Response format

Results are paginated. The default page size is 25. Use the page and page_size query parameters to control pagination.

{
    "count": 100,
    "next": "https://sdm.akeneo.cloud/api/v1/jobs/?page=2",
    "previous": null,
    "results": [
        {
            "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            "name": "Job 1",
            "status": "done",
            "can_cancel": false,
            "creation_date": "2022-04-14T08:48:37.109159Z",
            "completion_date": "2022-04-17T09:53:32.12Z"
        }
    ]
}

next and previous contain the URL for the next and previous page respectively, or null if no such page exists.

Cancel an SDM job

To stop a job that hasn't finished yet, call:

POST https://sdm.akeneo.cloud/api/v1/jobs/{job_id}/cancel/

With your API token, you can cancel any job of your organization if you are an organization admin, and otherwise the jobs you created. A running step is stopped and the job gets the cancelled status. It can't be resumed: create a new job to start again.

Every job in the API responses has a can_cancel field. It is true when this call is allowed for you, so you can check it before cancelling.

When the job's state doesn't allow a cancel, the response is 409 Conflict with a code:

Example response:

{
    "detail": "The job is moving to its next step",
    "code": "job_moving_to_next_step"
}

A 403 response means you are neither an organization admin nor the job's creator. A 404 response means the job doesn't exist in your organization.

Once a job is cancelled, every request on one of its steps, whether it reads or changes it, and any request to send it back to a step, answers 409 Conflict with the code job_cancelled. You can still read the job itself, download its files and delete it.

Retrieve SDM job output data in JSON format

Once an SDM job has status: done, you can retrieve the output data in JSON format:

GET https://sdm.akeneo.cloud/api/v1/jobs/{job_id}/data/{output_format_id}/

Replace {job_id} with the job UUID and {output_format_id} with the ID of the output format configured for the project.

Example response:

[
    {
        "col1": "val1_1",
        "col2": "val2_1"
    }
]

The response is an array of objects, one per row of the output dataset. Each object's keys are the column names. Empty columns are omitted from the response.