Background Job
/
List background job

API Explorer (2.0.0)

The entire API V2 documentation is interactive and can be tested here. To the right side of every endpoint you will see a box with an example request. You can click on the "Try it" button to send a request to the server right from the docs. You will need to provide an API key by clicking the ApiKeyAuth_token blue text.

Languages
Servers
Instantly API Server

https://api.instantly.ai/

Mock server

https://developer.instantly.ai/_mock/api/v2/

Analytics

Endpoints related to analytics

Operations

Account

An email account that can be used to send campaigns

Operations

Campaign

A campaign that can be sent to a list of recipients

Operations

Email

A campaign email, a reply, a manually sent email, or any other email that's visible in the Unibox

Operations

Email Verification

A single email verification

Operations

Lead List

A list used to store leads

Operations

Inbox Placement Test

An inbox placement test

Operations

Inbox Placement Analytics

Analytics data for individual emails in inbox placement tests

Operations

Inbox Placement Blacklist & SpamAssassin Report

Report data for an inbox placement test

Operations

API Key

API Key

Operations

Account Campaign Mapping

Account Campaign Mapping

Operations

Lead

A lead entity representing an individual lead

Operations

Background Job

A background job that can be used to perform long-running tasks

Operations

Background Job

A background job that can be used to perform long-running tasks

idstringread-onlyrequired

Unique identifier for the background job

Example: "675266e304a8e55b17f0228b"
workspace_idstring(uuid)read-onlyrequired

Workspace ID

Example: "0197fb57-4200-7db8-ab7d-f21f397dec62"
typestringrequired

Type of background job

Enum ValueDescription
move-leads

Move Leads

import-leads

Import Leads

export-leads

Export Leads

Example: "move-leads"
progressnumber[ 0 .. 100 ]required

Progress of the job as a percentage (from 0 to 100)

Example: 0
statusstringrequired

Job status

Enum ValueDescription
pending

The background job is waiting in the queue to be processed

in-progress

The background job is being processed

success

The background job has been successfully processed

failed

The background job has failed

Example: "pending"
created_atstringrequired

Timestamp when the job was created

Example: "2025-07-11T21:14:49.216Z"
updated_atstringrequired

Timestamp when the job was last updated

Example: "2025-07-11T21:14:49.216Z"
user_idnull or string(uuid)read-only

The id of the user that triggered the action that created the job

Example: "0197fb57-4200-7db8-ab7d-f220724c8345"
entity_idnull or string(uuid)

The id of the entity that the job is related to

Example: "0197fb57-4200-7db8-ab7d-f221e8ac378f"
entity_typestring

Type of entity

Enum ValueDescription
list

The entity is a lead list

campaign

The entity is a campaign

Example: "list"
dataobject

Data about the job, used to store any additional information we need to process the job

{
  "id": "675266e304a8e55b17f0228b",
  "workspace_id": "0197fb57-4200-7db8-ab7d-f21f397dec62",
  "user_id": "0197fb57-4200-7db8-ab7d-f220724c8345",
  "type": "move-leads",
  "entity_id": "0197fb57-4200-7db8-ab7d-f221e8ac378f",
  "entity_type": "list",
  "data": {},
  "progress": 0,
  "status": "pending",
  "created_at": "2025-07-11T21:14:49.216Z",
  "updated_at": "2025-07-11T21:14:49.216Z"
}

List background job

Request

Requires one of the following scopes: background-jobs:read, background-jobs:all, all:read, all:all

Query
limitinteger[ 1 .. 100 ]

The number of items to return

Example: limit=10
starting_afterstring
Example: starting_after=507f1f77bcf86cd799439011
idsstring

The ID of the job. Multiple IDs can be provided as a comma-separated list

Example: ids=676f3caadedbfe9abea3bab4
included_idsstring

The ID of the job to be included in the response. Multiple IDs can be provided as a comma-separated list

Example: included_ids=676f3caadedbfe9abea3bab4
excluded_idsstring

The ID of the job to be excluded from the response. Multiple IDs can be provided as a comma-separated list

Example: excluded_ids=676f3caadedbfe9abea3bab4
typestring

The type of the job

Enum"move-leads""import-leads""export-leads"
Example: type=move-leads
entity_typestring

The type of the entity

Enum"list""campaign"
Example: entity_type=list
entity_idstring

The ID of the entity. Multiple IDs can be provided as a comma-separated list

Example: entity_id=676f3caadedbfe9abea3bab4
statusstring

The status of the job. Multiple statuses can be provided as a comma-separated list. Valid statuses are: pending, in-progress, success, failed

Example: status=pending,in-progress
sort_columnstring

The column to sort the results by

Enum ValueDescription
created_at

Created at

updated_at

Updated at

Example: sort_column=created_at
sort_orderstring

The order to sort the results by

Enum ValueDescription
asc

Ascending

desc

Descending

Example: sort_order=desc
curl -i -X GET \
  'https://api.instantly.ai/api/v2/background-jobs?entity_id=676f3caadedbfe9abea3bab4&entity_type=list&excluded_ids=676f3caadedbfe9abea3bab4&ids=676f3caadedbfe9abea3bab4&included_ids=676f3caadedbfe9abea3bab4&limit=10&sort_column=created_at&sort_order=desc&starting_after=507f1f77bcf86cd799439011&status=pending%2Cin-progress&type=move-leads' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The list of Background Job

Bodyapplication/json
itemsArray of objects(Background Job)required
items[].​idstringread-onlyrequired

Unique identifier for the background job

Example: "675266e304a8e55b17f0228b"
items[].​workspace_idstring(uuid)read-onlyrequired

Workspace ID

Example: "0197fb57-4200-7db8-ab7d-f21f397dec62"
items[].​typestringrequired

Type of background job

Enum ValueDescription
move-leads

Move Leads

import-leads

Import Leads

export-leads

Export Leads

Example: "move-leads"
items[].​progressnumber[ 0 .. 100 ]required

Progress of the job as a percentage (from 0 to 100)

Example: 0
items[].​statusstringrequired

Job status

Enum ValueDescription
pending

The background job is waiting in the queue to be processed

in-progress

The background job is being processed

success

The background job has been successfully processed

failed

The background job has failed

Example: "pending"
items[].​created_atstringrequired

Timestamp when the job was created

Example: "2025-07-11T21:14:49.216Z"
items[].​updated_atstringrequired

Timestamp when the job was last updated

Example: "2025-07-11T21:14:49.216Z"
items[].​user_idnull or string(uuid)read-only

The id of the user that triggered the action that created the job

Example: "0197fb57-4200-7db8-ab7d-f220724c8345"
items[].​entity_idnull or string(uuid)

The id of the entity that the job is related to

Example: "0197fb57-4200-7db8-ab7d-f221e8ac378f"
items[].​entity_typestring

Type of entity

Enum ValueDescription
list

The entity is a lead list

campaign

The entity is a campaign

Example: "list"
items[].​dataobject

Data about the job, used to store any additional information we need to process the job

next_starting_afterstring

The filter for getting the next items after this one, this could either be a UUID, a MongoDB ID, a timestamp, on an email depending on the specific API

Example: "0197fb57-4ec6-7cd7-8aa2-041b7531335d"
Response
application/json
{
  "items": [
    { … }
  ],
  "next_starting_after": "0197fb57-4ec6-7cd7-8aa2-041b7531335d"
}

Get background job

Request

Requires one of the following scopes: background-jobs:read, background-jobs:all, all:read, all:all

Path
idstringrequired

The ID of the requested item

Example: 68717eccf2e974fea66616b9
curl -i -X GET \
  https://api.instantly.ai/api/v2/background-jobs/68717eccf2e974fea66616b9 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The requested Background Job

Bodyapplication/json
idstringread-onlyrequired

Unique identifier for the background job

Example: "675266e304a8e55b17f0228b"
workspace_idstring(uuid)read-onlyrequired

Workspace ID

Example: "0197fb57-4200-7db8-ab7d-f21f397dec62"
typestringrequired

Type of background job

Enum ValueDescription
move-leads

Move Leads

import-leads

Import Leads

export-leads

Export Leads

Example: "move-leads"
progressnumber[ 0 .. 100 ]required

Progress of the job as a percentage (from 0 to 100)

Example: 0
statusstringrequired

Job status

Enum ValueDescription
pending

The background job is waiting in the queue to be processed

in-progress

The background job is being processed

success

The background job has been successfully processed

failed

The background job has failed

Example: "pending"
created_atstringrequired

Timestamp when the job was created

Example: "2025-07-11T21:14:49.216Z"
updated_atstringrequired

Timestamp when the job was last updated

Example: "2025-07-11T21:14:49.216Z"
user_idnull or string(uuid)read-only

The id of the user that triggered the action that created the job

Example: "0197fb57-4200-7db8-ab7d-f220724c8345"
entity_idnull or string(uuid)

The id of the entity that the job is related to

Example: "0197fb57-4200-7db8-ab7d-f221e8ac378f"
entity_typestring

Type of entity

Enum ValueDescription
list

The entity is a lead list

campaign

The entity is a campaign

Example: "list"
dataobject

Data about the job, used to store any additional information we need to process the job

Response
application/json
{
  "id": "675266e304a8e55b17f0228b",
  "workspace_id": "0197fb57-4200-7db8-ab7d-f21f397dec62",
  "user_id": "0197fb57-4200-7db8-ab7d-f220724c8345",
  "type": "move-leads",
  "entity_id": "0197fb57-4200-7db8-ab7d-f221e8ac378f",
  "entity_type": "list",
  "data": {},
  "progress": 0,
  "status": "pending",
  "created_at": "2025-07-11T21:14:49.216Z",
  "updated_at": "2025-07-11T21:14:49.216Z"
}

Custom Tag

A custom tag for organizing and categorizing accounts and campaigns. You can use them as filters in apis that list accounts and campaigns.

Operations

Block List Entry

A blocked email or domain

Operations

Lead Label

A custom label for categorizing and managing leads

Operations

Workspace

A workspace entity representing a workspace

Operations

Workspace Group Member

A member of a workspace group. You can use the endpoints within this entity to manage the members of a workspace group.

Operations

Workspace Member

A member of a workspace with associated user details

Operations

Campaign Subsequence

A subsequence entity representing a follow-up sequence

Operations

Audit Log

Audit log records for tracking system activities

Operations

Schemas