Get Batch Add to List Job

Retrieve the status of a batch add-to-list job created via POST /v1/lists/batch-add-to-list-jobs.

While status is running, results and summary are omitted. Once status becomes completed, results carries the per-item outcome and summary carries the per-outcome counts (including failed_count) together with list_size_before and list_size_after. A job created from an advanced_search selection reports summary counts only — no per-item results. On failed, errors describes the failure.

Credit Note: This endpoint does not consume credits.

INFO

Requires the lists:read OAuth2 scope.

application/json

Batch add-to-list job status retrieved

Bodyapplication/json

Examples

Job completed — results and summary populatedAdvanced-search job completed — summary only, no per-item resultsJob failed — errors populated, no resultsAdvanced-search job failed — selection would exceed the list's capacityJob still running — no results yet

{
    "data": {
        "attributes": {
            "completed_at": "2026-05-13T12:00:02Z",
            "configuration": {
                "items": [
                    {
                        "id": "159001425",
                        "type": "company"
                    },
                    {
                        "id": "159001426",
                        "type": "company"
                    }
                ],
                "list_id": "company_123"
            },
            "created_at": "2026-05-13T12:00:00Z",
            "results": [
                {
                    "id": "159001425",
                    "status": "added",
                    "type": "company"
                },
                {
                    "id": "159001426",
                    "status": "added",
                    "type": "company"
                }
            ],
            "status": "completed",
            "summary": {
                "added": 2,
                "already_present": 0,
                "failed_count": 0,
                "list_size_after": 53,
                "list_size_before": 51,
                "not_found": 0,
                "scope_mismatch": 0
            }
        },
        "id": "job_550e8400-e29b-41d4-a716-446655440000",
        "type": "batch_add_to_list_job"
    },
    "meta": {
        "request_id": "cf054205-dd8c-4473-8689-07c30fe0789f"
    }
}

Request

Request Code Samples

Responses