Reference

Campaigns

Read campaigns and their stats, enroll leads, and pause or resume a campaign.

Campaigns are built and launched in the app, where the sequence is validated. The API reads them, adds leads, and pauses or resumes them. Enrollment goes through the same checks as the app: suppressed leads and leads active in another campaign are skipped and counted.

List campaigns

GET/api/v1/campaignsScope campaigns:read

Campaigns newest first, each with enrollment counts. Filter with status.

Parameters

NameInTypeDescription
cursorquerystringOpaque cursor from the previous page's nextCursor.
limitqueryintegerPage size. 1 to 100. Default 50.
statusquerystringCurrent status. One of draft, scheduled, active, paused, completed, archived.

Example request

curl -s "https://app.graphkit.com/api/v1/campaigns" \
  -H "Authorization: Bearer $GRAPHKIT_API_KEY"

Response 200

FieldTypeDescription
dataarray of objectThe page of results, newest first.
data[].idstring (uuid)UUID.
data[].namestring
data[].descriptionstring or null
data[].statusstringCurrent status. One of draft, scheduled, active, paused, completed, archived.
data[].channelsarray of stringChannels the sequence uses.
data[].dryRunbooleanDry-run campaigns record actions without sending.
data[].stopOnReplybooleanA reply on any channel stops the lead.
data[].isDemobooleanTrue for demo data in a demo workspace.
data[].launchedAtstring (date-time) or null
data[].pausedAtstring (date-time) or null
data[].completedAtstring (date-time) or null
data[].createdAtstring (date-time)When it was created (RFC 3339, UTC).
data[].enrollmentsobjectEnrollment counts.
data[].enrollments.totalinteger
data[].enrollments.activeinteger
data[].enrollments.completedinteger
data[].enrollments.stoppedinteger
nextCursorstring or nullPass back as cursor for the next page; null on the last page.
{
  "data": [
    {
      "id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
      "name": "Q1 founders, UK",
      "description": null,
      "status": "active",
      "channels": [
        "string"
      ],
      "dryRun": false,
      "stopOnReply": true,
      "isDemo": false,
      "launchedAt": "2026-11-15T10:04:05Z",
      "pausedAt": null,
      "completedAt": null,
      "createdAt": "2026-11-15T10:04:05Z",
      "enrollments": {
        "total": 12,
        "active": 12,
        "completed": 12,
        "stopped": 12
      }
    }
  ],
  "nextCursor": null
}

Errors

StatusCode and meaning
401invalid_api_key: the key is missing, unknown or revoked.
403insufficient_scope: the key lacks the scope this endpoint needs.
429rate_limited: more than 300 requests in a minute; wait for Retry-After.

Get a campaign

GET/api/v1/campaigns/{id}Scope campaigns:read

One campaign with its enrollment counts.

Parameters

NameInTypeDescription
idpathstring (uuid)The resource id.

Example request

curl -s "https://app.graphkit.com/api/v1/campaigns/0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99" \
  -H "Authorization: Bearer $GRAPHKIT_API_KEY"

Response 200

FieldTypeDescription
idstring (uuid)UUID.
namestring
descriptionstring or null
statusstringCurrent status. One of draft, scheduled, active, paused, completed, archived.
channelsarray of stringChannels the sequence uses.
dryRunbooleanDry-run campaigns record actions without sending.
stopOnReplybooleanA reply on any channel stops the lead.
isDemobooleanTrue for demo data in a demo workspace.
launchedAtstring (date-time) or null
pausedAtstring (date-time) or null
completedAtstring (date-time) or null
createdAtstring (date-time)When it was created (RFC 3339, UTC).
enrollmentsobjectEnrollment counts.
enrollments.totalinteger
enrollments.activeinteger
enrollments.completedinteger
enrollments.stoppedinteger
{
  "id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
  "name": "Q1 founders, UK",
  "description": null,
  "status": "active",
  "channels": [
    "string"
  ],
  "dryRun": false,
  "stopOnReply": true,
  "isDemo": false,
  "launchedAt": "2026-11-15T10:04:05Z",
  "pausedAt": null,
  "completedAt": null,
  "createdAt": "2026-11-15T10:04:05Z",
  "enrollments": {
    "total": 12,
    "active": 12,
    "completed": 12,
    "stopped": 12
  }
}

Errors

StatusCode and meaning
401invalid_api_key: the key is missing, unknown or revoked.
403insufficient_scope: the key lacks the scope this endpoint needs.
404not_found: no such resource in this key's workspace.
429rate_limited: more than 300 requests in a minute; wait for Retry-After.

Get campaign stats

GET/api/v1/campaigns/{id}/statsScope campaigns:read

The same metrics as the app's analytics page for this campaign: totals for the range, totals for the previous range of the same length, and one row per day. Days are local to the workspace time zone.

Pass from and to (YYYY-MM-DD, inclusive), or days for the last N days. The default is the last 30 days. Metric definitions are in Analytics. Rates are null when their denominator is 0.

Parameters

NameInTypeDescription
idpathstring (uuid)The resource id.
fromquerystring (date)First day (inclusive, local to the workspace). Send with to.
toquerystring (date)Last day (inclusive).
daysqueryintegerLast N days ending today, when from/to are absent. 1 to 366.

Example request

curl -s "https://app.graphkit.com/api/v1/campaigns/0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99/stats?days=30" \
  -H "Authorization: Bearer $GRAPHKIT_API_KEY"

Response 200

FieldTypeDescription
campaignIdstring (uuid)Campaign id.
rangeobjectThe range the totals cover.
range.fromstring (date)
range.tostring (date)
range.daysintegerOne row per local day.
range.timezonestring
totalsobjectTotals for the range.
totals.invitesSentintegerLinkedIn invitations sent.
totals.invitesAcceptedintegerInvites sent in the range whose lead later connected with the same account.
totals.acceptanceRatenumber or nullinvitesAccepted / invitesSent, or null with no invites.
totals.messagesSentintegercampaignMessages + manualMessages.
totals.campaignMessagesintegerMessage and voice-note steps that succeeded.
totals.manualMessagesintegerMessages sent by teammates or the API.
totals.inmailsSentintegerInMails sent.
totals.profileVisitsintegerLinkedIn profile visits.
totals.followsintegerFollows.
totals.likesintegerPost reactions.
totals.contactedintegerConversations with an outbound message in the range.
totals.repliesintegerConversations whose first inbound message in the range follows an outbound one.
totals.replyRatenumber or nullreplies / contacted, or null.
totals.positiveRepliesintegerReplies in conversations labelled Interested, Positive, Meeting booked, Hot lead, Qualified or similar.
totals.positiveRatenumber or nullpositiveReplies / replies, or null.
totals.messagesReceivedintegerInbound messages.
totals.newConnectionsintegerNew LinkedIn connections.
totals.failedActionsintegerSteps that ended failed.
totals.emailHandoffsintegerLeads handed to a connected email platform (succeeded email_handoff steps).
totals.emailRepliesintegerFirst email reply per lead, connection and platform campaign, as reported by the email platform (source = platform). Not included in replies.
previousTotalsobjectTotals for the previous range of the same length. Same fields as totals.
daysarray of objectOne row per local day.
days[].invitesSentintegerLinkedIn invitations sent.
days[].invitesAcceptedintegerInvites sent in the range whose lead later connected with the same account.
days[].acceptanceRatenumber or nullinvitesAccepted / invitesSent, or null with no invites.
days[].messagesSentintegercampaignMessages + manualMessages.
days[].campaignMessagesintegerMessage and voice-note steps that succeeded.
days[].manualMessagesintegerMessages sent by teammates or the API.
days[].inmailsSentintegerInMails sent.
days[].profileVisitsintegerLinkedIn profile visits.
days[].followsintegerFollows.
days[].likesintegerPost reactions.
days[].contactedintegerConversations with an outbound message in the range.
days[].repliesintegerConversations whose first inbound message in the range follows an outbound one.
days[].replyRatenumber or nullreplies / contacted, or null.
days[].positiveRepliesintegerReplies in conversations labelled Interested, Positive, Meeting booked, Hot lead, Qualified or similar.
days[].positiveRatenumber or nullpositiveReplies / replies, or null.
days[].messagesReceivedintegerInbound messages.
days[].newConnectionsintegerNew LinkedIn connections.
days[].failedActionsintegerSteps that ended failed.
days[].emailHandoffsintegerLeads handed to a connected email platform (succeeded email_handoff steps).
days[].emailRepliesintegerFirst email reply per lead, connection and platform campaign, as reported by the email platform (source = platform). Not included in replies.
days[].datestring (date)Local day.
{
  "campaignId": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
  "range": {
    "from": "2026-11-15",
    "to": "2026-11-15",
    "days": 12,
    "timezone": "Europe/London"
  },
  "totals": {
    "invitesSent": 12,
    "invitesAccepted": 12,
    "acceptanceRate": 0.25,
    "messagesSent": 12,
    "campaignMessages": 12,
    "manualMessages": 12,
    "inmailsSent": 12,
    "profileVisits": 12,
    "follows": 12,
    "likes": 12,
    "contacted": 12,
    "replies": 12,
    "replyRate": 0.25,
    "positiveReplies": 12,
    "positiveRate": 0.25,
    "messagesReceived": 12,
    "newConnections": 12,
    "failedActions": 12,
    "emailHandoffs": 12,
    "emailReplies": 12
  },
  "previousTotals": {
    "invitesSent": 12,
    "invitesAccepted": 12,
    "acceptanceRate": 0.25,
    "messagesSent": 12,
    "campaignMessages": 12,
    "manualMessages": 12,
    "inmailsSent": 12,
    "profileVisits": 12,
    "follows": 12,
    "likes": 12,
    "contacted": 12,
    "replies": 12,
    "replyRate": 0.25,
    "positiveReplies": 12,
    "positiveRate": 0.25,
    "messagesReceived": 12,
    "newConnections": 12,
    "failedActions": 12,
    "emailHandoffs": 12,
    "emailReplies": 12
  },
  "days": [
    {
      "invitesSent": 12,
      "invitesAccepted": 12,
      "acceptanceRate": 0.25,
      "messagesSent": 12,
      "campaignMessages": 12,
      "manualMessages": 12,
      "inmailsSent": 12,
      "profileVisits": 12,
      "follows": 12,
      "likes": 12,
      "contacted": 12,
      "replies": 12,
      "replyRate": 0.25,
      "positiveReplies": 12,
      "positiveRate": 0.25,
      "messagesReceived": 12,
      "newConnections": 12,
      "failedActions": 12,
      "emailHandoffs": 12,
      "emailReplies": 12,
      "date": "2026-11-15"
    }
  ]
}

Errors

StatusCode and meaning
401invalid_api_key: the key is missing, unknown or revoked.
403insufficient_scope: the key lacks the scope this endpoint needs.
404not_found: no such resource in this key's workspace.
429rate_limited: more than 300 requests in a minute; wait for Retry-After.

Add leads to a campaign

POST/api/v1/campaigns/{id}/leadsScope campaigns:write

Adds leads as pending enrollments at the entry step, with leadIds (1 to 1000) or every lead of listId. The scheduler starts them inside the campaign's sending windows.

Leads already in the campaign, suppressed leads and leads active in another campaign of the workspace are skipped and counted. Completed and archived campaigns return 409 invalid_state.

Parameters

NameInTypeDescription
idpathstring (uuid)The resource id.
Idempotency-KeyheaderstringReplays the stored response for 24 hours (header Idempotent-Replayed: true). Reusing a key with a different request is 422; while the first request runs, 409. Up to 255 characters.

Request body

leadIds (1–1000); campaigns also accept listId instead.

FieldTypeRequiredDescription
leadIdsarray of string (uuid)NoLead ids. Up to 1000 items.
listIdstring (uuid)NoOnly leads in this list.

Example request

curl -s -X POST "https://app.graphkit.com/api/v1/campaigns/0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99/leads" \
  -H "Authorization: Bearer $GRAPHKIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"listId":"0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99"}'

Response 200

FieldTypeDescription
addedintegerNew pending enrollments.
alreadyPresentintegerLeads already enrolled in this campaign.
suppressedintegerLeads skipped because one of their identities is suppressed (opt-out, blocklist).
activeElsewhereintegerLeads skipped because they are active in another campaign of the workspace.
unknownLeadIdsarray of string (uuid)
{
  "added": 12,
  "alreadyPresent": 12,
  "suppressed": 12,
  "activeElsewhere": 12,
  "unknownLeadIds": []
}

Errors

StatusCode and meaning
401invalid_api_key: the key is missing, unknown or revoked.
403insufficient_scope: the key lacks the scope this endpoint needs.
404not_found: no such resource in this key's workspace.
400invalid_lead_ids: Neither leadIds nor listId, or more than 1000 ids.
400invalid_list_id: listId is not a valid id.
409invalid_state: The campaign is completed or archived.
429rate_limited: more than 300 requests in a minute; wait for Retry-After.

Pause a campaign

POST/api/v1/campaigns/{id}/pauseScope campaigns:write

Pauses an active or scheduled campaign. Leads keep their place and continue from it on resume.

Parameters

NameInTypeDescription
idpathstring (uuid)The resource id.
Idempotency-KeyheaderstringReplays the stored response for 24 hours (header Idempotent-Replayed: true). Reusing a key with a different request is 422; while the first request runs, 409. Up to 255 characters.

Example request

curl -s -X POST "https://app.graphkit.com/api/v1/campaigns/0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99/pause" \
  -H "Authorization: Bearer $GRAPHKIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Response 200

FieldTypeDescription
idstring (uuid)UUID.
namestring
descriptionstring or null
statusstringCurrent status. One of draft, scheduled, active, paused, completed, archived.
channelsarray of stringChannels the sequence uses.
dryRunbooleanDry-run campaigns record actions without sending.
stopOnReplybooleanA reply on any channel stops the lead.
isDemobooleanTrue for demo data in a demo workspace.
launchedAtstring (date-time) or null
pausedAtstring (date-time) or null
completedAtstring (date-time) or null
createdAtstring (date-time)When it was created (RFC 3339, UTC).
enrollmentsobjectEnrollment counts.
enrollments.totalinteger
enrollments.activeinteger
enrollments.completedinteger
enrollments.stoppedinteger
{
  "id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
  "name": "Q1 founders, UK",
  "description": null,
  "status": "active",
  "channels": [
    "string"
  ],
  "dryRun": false,
  "stopOnReply": true,
  "isDemo": false,
  "launchedAt": "2026-11-15T10:04:05Z",
  "pausedAt": null,
  "completedAt": null,
  "createdAt": "2026-11-15T10:04:05Z",
  "enrollments": {
    "total": 12,
    "active": 12,
    "completed": 12,
    "stopped": 12
  }
}

Errors

StatusCode and meaning
401invalid_api_key: the key is missing, unknown or revoked.
403insufficient_scope: the key lacks the scope this endpoint needs.
404not_found: no such resource in this key's workspace.
409invalid_state: The campaign is not active or scheduled.
429rate_limited: more than 300 requests in a minute; wait for Retry-After.

Resume a campaign

POST/api/v1/campaigns/{id}/resumeScope campaigns:write

Resumes a paused campaign and emits campaign.started. Draft campaigns are launched in the app, where the sequence is validated.

Parameters

NameInTypeDescription
idpathstring (uuid)The resource id.
Idempotency-KeyheaderstringReplays the stored response for 24 hours (header Idempotent-Replayed: true). Reusing a key with a different request is 422; while the first request runs, 409. Up to 255 characters.

Example request

curl -s -X POST "https://app.graphkit.com/api/v1/campaigns/0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99/resume" \
  -H "Authorization: Bearer $GRAPHKIT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Response 200

FieldTypeDescription
idstring (uuid)UUID.
namestring
descriptionstring or null
statusstringCurrent status. One of draft, scheduled, active, paused, completed, archived.
channelsarray of stringChannels the sequence uses.
dryRunbooleanDry-run campaigns record actions without sending.
stopOnReplybooleanA reply on any channel stops the lead.
isDemobooleanTrue for demo data in a demo workspace.
launchedAtstring (date-time) or null
pausedAtstring (date-time) or null
completedAtstring (date-time) or null
createdAtstring (date-time)When it was created (RFC 3339, UTC).
enrollmentsobjectEnrollment counts.
enrollments.totalinteger
enrollments.activeinteger
enrollments.completedinteger
enrollments.stoppedinteger
{
  "id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
  "name": "Q1 founders, UK",
  "description": null,
  "status": "active",
  "channels": [
    "string"
  ],
  "dryRun": false,
  "stopOnReply": true,
  "isDemo": false,
  "launchedAt": "2026-11-15T10:04:05Z",
  "pausedAt": null,
  "completedAt": null,
  "createdAt": "2026-11-15T10:04:05Z",
  "enrollments": {
    "total": 12,
    "active": 12,
    "completed": 12,
    "stopped": 12
  }
}

Errors

StatusCode and meaning
401invalid_api_key: the key is missing, unknown or revoked.
403insufficient_scope: the key lacks the scope this endpoint needs.
404not_found: no such resource in this key's workspace.
402payment_overdue: The organization is past the payment grace period, so launches are blocked.
409invalid_state: The campaign is not paused.
429rate_limited: more than 300 requests in a minute; wait for Retry-After.

On this page