Analytics

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

Get warmup analytics

Request

Requires one of the following scopes: accounts:read, accounts:all, all:read, all:all

Bodyapplication/jsonrequired
emailsArray of strings[ 1 .. 100 ] itemsrequired

List of emails to get warmup analytics for. The emails should be attached to accounts in your workspace.

Example: ["user@example.com"]
curl -i -X POST \
  https://api.instantly.ai/api/v2/accounts/warmup-analytics \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "emails": [
      "user@example.com"
    ]
  }'

Responses

Default Response

Bodyapplication/json
email_date_dataobject
Example: {"example1@example.com":{"2023-10-01":{"sent":10,"landed_inbox":8,"landed_spam":2,"received":10},"2023-10-02":{"sent":5,"landed_inbox":5,"received":5}},"example2@example.com":{"2023-10-01":{"sent":7,"landed_inbox":7,"received":7}}}
aggregate_dataobject
Example: {"example1@example.com":{"sent":15,"landed_inbox":13,"landed_spam":2,"received":15,"health_score_label":"87%","health_score":87},"example2@example.com":{"sent":7,"landed_inbox":7,"health_score_label":"100%","health_score":100}}
Response
application/json
{
  "email_date_data": {
    "example1@example.com": { … },
    "example2@example.com": { … }
  },
  "aggregate_data": {
    "example1@example.com": { … },
    "example2@example.com": { … }
  }
}

Test account vitals

Request

Requires one of the following scopes: accounts:read, accounts:all, all:read, all:all

Bodyapplication/json
accountsArray of strings
Example: ["user@example.com"]
curl -i -X POST \
  https://api.instantly.ai/api/v2/accounts/test/vitals \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

Default Response

Bodyapplication/json
statusstring
Example: "success"
success_listArray of objects
failure_listArray of objects
Response
application/json
{
  "status": "success",
  "success_list": [
    { … }
  ],
  "failure_list": [
    { … }
  ]
}

Get campaign(s) analytics

Request

Get analytics for one or multiple campaigns. Specify the id field to get the analytics for a single campaign, or leave it empty to get the analytics for all campaigns

Query
idstring(uuid)

A campaign ID to get the analytics for. Leave this field empty to get the analytics for all campaigns

Example: id=019769d6-da17-7d0b-a17c-1f5ce16252d6
idsArray of strings(uuid)
Example: ids=019769d6-da17-7d0b-a17c-1f5d5bf55462
start_datestring

Start date

Example: start_date=2024-01-01
end_datestring

End date

Example: end_date=2024-01-01
exclude_total_leads_countboolean

Exclude the total leads from the result. Setting this to true will considerably decrease the response time

Default false
Example: exclude_total_leads_count=true
curl -i -X GET \
  'https://api.instantly.ai/api/v2/campaigns/analytics?end_date=2024-01-01&exclude_total_leads_count=true&id=019769d6-da17-7d0b-a17c-1f5ce16252d6&ids=019769d6-da17-7d0b-a17c-1f5d5bf55462&start_date=2024-01-01' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Default Response

Bodyapplication/jsonArray [
campaign_namestringrequired

The name of the campaign

Example: "My Test Campaign"
campaign_idstring(uuid)required

The ID of the campaign

Example: "019769d6-da18-7a3a-bfe3-6e3194b330ad"
campaign_statusnumberrequired

The campaign status

Enum ValueDescription
0

Draft

1

Active

2

Paused

3

Completed

4

Running Subsequences

-99

Account Suspended

-1

Accounts Unhealthy

-2

Bounce Protect

Example: 1
campaign_is_evergreenbooleanrequired

Whether the campaign is evergreen

Example: true
leads_countintegerrequired

The total number of leads

Example: 1500
contacted_countintegerrequired

Number of leads for whom the sequence has started

Example: 1200
open_countintegerrequired

The number of leads that opened at least one email

Example: 800
reply_countintegerrequired

The number of leads that replied to at least one email

Example: 300
link_click_countintegerrequired

The number of links that got clicked

Example: 800
bounced_countintegerrequired

The number of bounced leads

Example: 50
unsubscribed_countintegerrequired

The number of unsubscribed leads

Example: 20
completed_countintegerrequired

The number of leads that the campaign was completed for

Example: 1100
emails_sent_countintegerrequired

The total number of sent emails

Example: 5000
new_leads_contacted_countintegerrequired

The total number of new leads contacted

Example: 200
total_opportunitiesintegerrequired

The total number of unique opportunities created

Example: 10
total_opportunity_valuenumberrequired

The total value of opportunities created

Example: 1000
]
Response
application/json
[
  {
    "campaign_name": "My Test Campaign",
    "campaign_id": "019769d6-da18-7a3a-bfe3-6e3194b330ad",
    "campaign_status": 1,
    "campaign_is_evergreen": true,
    "leads_count": 1500,
    "contacted_count": 1200,
    "open_count": 800,
    "reply_count": 300,
    "link_click_count": 800,
    "bounced_count": 50,
    "unsubscribed_count": 20,
    "completed_count": 1100,
    "emails_sent_count": 5000,
    "new_leads_contacted_count": 200,
    "total_opportunities": 10,
    "total_opportunity_value": 1000
  }
]

Get campaign(s) analytics overview

Request

Get analytics overview for one or multiple campaigns. Specify the id field to get the analytics overview for a single campaign, or leave it empty to get the analytics overview for all campaigns

Query
idstring(uuid)

A campaign ID to get the analytics overview for. Leave this field empty to get the analytics overview for all campaigns

Example: id=019769d6-da19-7011-9351-2ffb35069e33
idsArray of strings(uuid)
Example: ids=019769d6-da19-7011-9351-2ffc4bb68fb2
start_datestring

Start date

Example: start_date=2024-01-01
end_datestring

End date

Example: end_date=2024-01-01
campaign_statusnumber

Filter by campaign status (only the analytics for the campaigns with the specified status will be returned)

Enum ValueDescription
0

Draft

1

Active

2

Paused

3

Completed

4

Running Subsequences

-99

Account Suspended

-1

Accounts Unhealthy

-2

Bounce Protect

Example: campaign_status=1
curl -i -X GET \
  'https://api.instantly.ai/api/v2/campaigns/analytics/overview?campaign_status=1&end_date=2024-01-01&id=019769d6-da19-7011-9351-2ffb35069e33&ids=019769d6-da19-7011-9351-2ffc4bb68fb2&start_date=2024-01-01' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Default Response

Bodyapplication/json
open_countinteger

The total number of times the emails were opened, including duplicates

Example: 800
open_count_uniqueinteger

The number of emails that got opened (for the first time only)

Example: 800
open_count_unique_by_stepinteger

The unique number of times the emails were opened (counted once per lead, step, and campaign)

Example: 800
link_click_countinteger

The number of links that got clicked

Example: 800
link_click_count_uniqueinteger

The number of links that got clicked (for the first time)

Example: 800
link_click_count_unique_by_stepinteger

The unique number of links that got clicked, per step (counted once per lead, step, and campaign)

Example: 800
reply_countinteger

The number of leads that replied to at least one email

Example: 300
reply_count_uniqueinteger

The number of leads that replied to at least one email (for the first time only)

Example: 300
reply_count_unique_by_stepinteger

The unique number of leads that replied to at least one email, per step (counted once per lead, step, and campaign)

Example: 300
bounced_countinteger

The number of bounced leads

Example: 50
unsubscribed_countinteger

The number of unsubscribed leads

Example: 20
completed_countinteger

The number of leads that the campaign was completed for

Example: 1100
emails_sent_countinteger

The total number of sent emails

Example: 5000
new_leads_contacted_countinteger

The total number of new leads contacted

Example: 200
total_opportunitiesinteger

The total number of unique opportunities created

Example: 10
total_opportunity_valuenumber

The total value of opportunities created

Example: 1000
total_interestedinteger

The total number of interested opportunities created

Example: 103
total_meeting_bookedinteger

The total number of meeting booked opportunities created

Example: 45
total_meeting_completedinteger

The total number of meeting completed opportunities created

Example: 12
total_closedinteger

The total number of closed opportunities created

Example: 10
Response
application/json
{
  "open_count": 800,
  "open_count_unique": 800,
  "open_count_unique_by_step": 800,
  "link_click_count": 800,
  "link_click_count_unique": 800,
  "link_click_count_unique_by_step": 800,
  "reply_count": 300,
  "reply_count_unique": 300,
  "reply_count_unique_by_step": 300,
  "bounced_count": 50,
  "unsubscribed_count": 20,
  "completed_count": 1100,
  "emails_sent_count": 5000,
  "new_leads_contacted_count": 200,
  "total_opportunities": 10,
  "total_opportunity_value": 1000,
  "total_interested": 103,
  "total_meeting_booked": 45,
  "total_meeting_completed": 12,
  "total_closed": 10
}

Get daily campaign analytics

Request

Get campaign daily analytics

Query
campaign_idstring(uuid)

Campaign ID (optional). Leave this field empty to get the analytics for all campaigns

Example: campaign_id=019769d6-da1a-7d7e-b441-8ad06463db37
start_datestring

Start date

Example: start_date=2024-01-01
end_datestring

End date

Example: end_date=2024-01-01
campaign_statusnumber

Filter by campaign status (only the analytics for the campaigns with the specified status will be returned)

Enum ValueDescription
0

Draft

1

Active

2

Paused

3

Completed

4

Running Subsequences

-99

Account Suspended

-1

Accounts Unhealthy

-2

Bounce Protect

Example: campaign_status=1
curl -i -X GET \
  'https://api.instantly.ai/api/v2/campaigns/analytics/daily?campaign_id=019769d6-da1a-7d7e-b441-8ad06463db37&campaign_status=1&end_date=2024-01-01&start_date=2024-01-01' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Default Response

Bodyapplication/jsonArray [
datestring

The date of the analytics entry, in YYYY-MM-DD format

Example: "2025-03-01"
sentinteger

The total number of sent emails

Example: 5421
openedinteger

The total number of opened emails

Example: 99
unique_openedinteger

The total number of unique opened emails

Example: 60
repliesinteger

The total number of replies

Example: 60
unique_repliesinteger

The total number of unique replies

Example: 60
clicksinteger

The total number of links clicked

Example: 60
unique_clicksinteger

The total number of unique links clicked. Unique meaning from unique leads, not unique links. For instance, if a lead clicked a link 3 times, it will be counted as 1 unique click. If a lead clicked 3 different links, it will still be counted as 1 unique click

Example: 60
]
Response
application/json
[
  {
    "date": "2025-03-01",
    "sent": 5421,
    "opened": 99,
    "unique_opened": 60,
    "replies": 60,
    "unique_replies": 60,
    "clicks": 60,
    "unique_clicks": 60
  }
]

Get campaign steps analytics

Request

Get campaign steps analytics

Query
campaign_idstring(uuid)

Campaign ID (optional). Leave this field empty to get the analytics for all campaigns

Example: campaign_id=019769d6-da1b-79cf-a68e-1ee5f002fb7d
start_datestring

Start date

Example: start_date=2024-01-01
end_datestring

End date

Example: end_date=2024-01-01
curl -i -X GET \
  'https://api.instantly.ai/api/v2/campaigns/analytics/steps?campaign_id=019769d6-da1b-79cf-a68e-1ee5f002fb7d&end_date=2024-01-01&start_date=2024-01-01' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Default Response

Bodyapplication/jsonArray [
stepstring

The step number

Example: "1"
variantstring

The variant number, starting from 0. 0 = A, 1 = B, 2 = C, etc.

Example: "0"
sentinteger

The total number of sent emails

Example: 5421
openedinteger

The total number of opened emails

Example: 99
unique_openedinteger

The total number of opened emails

Example: 60
repliesinteger

The total number of replies

Example: 60
unique_repliesinteger

The total number of replies

Example: 60
clicksinteger

The total number of links clicked

Example: 60
unique_clicksinteger

The total number of unique links clicked. Unique meaning from unique leads, not unique links. For instance, if a lead clicked a link 3 times, it will be counted as 1 unique click. If a lead clicked 3 different links, it will still be counted as 1 unique click

Example: 60
]
Response
application/json
[
  {
    "step": "1",
    "variant": "0",
    "sent": 5421,
    "opened": 99,
    "unique_opened": 60,
    "replies": 60,
    "unique_replies": 60,
    "clicks": 60,
    "unique_clicks": 60
  }
]

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

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