Skip to content
ThreadkiteThreadkite Docs

Leads over time and by source, inbox, location, item, channel and owner

GET
/v1/reports/leads
curl --request GET \
  --url 'https://api.threadkite.app/v1/reports/leads?preset=today&granularity=day&inboxType=sales&sourceCategory=website&channel=email&trafficChannel=paid_search&touch=first' \
  --header 'Authorization: Bearer <token>'

Counted by the lead rule: one lead per contact, source and item within your lead period. Test leads are left out. Only the inboxes you can see. On Free, the basic reports (leads by source and first response times) cover the last 30 days; anything else returns 402.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
preset

Date range in your organisation’s time zone. Defaults to 30d (the last 30 days, today included); custom needs from and to. Dates without a preset are custom.

string
Allowed values: today 7d 30d this_month last_month custom

Date range in your organisation’s time zone. Defaults to 30d (the last 30 days, today included); custom needs from and to. Dates without a preset are custom.

from

First day (custom ranges), YYYY-MM-DD

string format: date

First day (custom ranges), YYYY-MM-DD

to

Last day, included (custom ranges)

string format: date

Last day, included (custom ranges)

granularity

Group charts over time by day or week. Defaults to days up to 62 days, else weeks

string
Allowed values: day week

Group charts over time by day or week. Defaults to days up to 62 days, else weeks

inboxId

Only this inbox (one you can see)

string format: uuid

Only this inbox (one you can see)

inboxType

Only inboxes of this type

string
Allowed values: sales service parts bodyshop general

Only inboxes of this type

locationId

Only leads at this location

string format: uuid

Only leads at this location

sourceId

Only leads from this source

string format: uuid

Only leads from this source

sourceCategory

Only sources of this kind

string
Allowed values: website marketplace website_provider dms social phone email other

Only sources of this kind

ownerUserId

Only threads this person owns, or unassigned for threads nobody owns

string
>= 1 characters <= 100 characters

Only threads this person owns, or unassigned for threads nobody owns

channel

Only leads on this channel

string
Allowed values: email sms whatsapp chat phone form api marketplace visit messenger instagram internal

Only leads on this channel

campaignId

Only leads from this campaign

string format: uuid

Only leads from this campaign

trafficChannel

Only leads whose visit came this way (paid search, email…)

string
Allowed values: paid_search paid_social display email sms affiliate organic_search organic_social referral direct other

Only leads whose visit came this way (paid search, email…)

touch

Sales, funnel and campaigns reports: credit each sale to the first lead in the look-back (first) or the latest before the sale (last, the default). Source, source type, channel, campaign and traffic channel filters then apply to that lead.

string
Allowed values: first last

Sales, funnel and campaigns reports: credit each sale to the first lead in the look-back (first) or the latest before the sale (last, the default). Source, source type, channel, campaign and traffic channel filters then apply to that lead.

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
range
required
object
from
required
string format: date
to
required
string format: date
days
required
number
preset
required
string
Allowed values: today 7d 30d this_month last_month custom
timeZone
required

Your organisation’s time zone

string
granularity
required
string
Allowed values: day week
previous
required

The period compared against

object
from
required
string format: date
to
required
string format: date
days
required
number
limited
required

The Free plan’s basic reports: only leads by source and first response times are filled in; other breakdowns are empty

boolean
leads
required

Leads by the lead rule (test leads left out)

number
previousLeads
required
number
series
required
Array<object>
object
date
required

The day, or the Monday of the week

string format: date
leads
required
number
previousLeads
required

The same point in the previous period (null past its end)

number
nullable
bySource
required

Most leads first

Array<object>
object
sourceId
required

Null for leads with no source

string format: uuid
nullable
name
required
string
category
required
string
nullable
Allowed values: website marketplace website_provider dms social phone email other
logoUrl
required

Logo address; null shows an initial badge

string
nullable
leads
required
number
previousLeads
required
number
byCategory
required
Array<object>
object
category
required
string
nullable
Allowed values: website marketplace website_provider dms social phone email other
leads
required
number
byInbox
required
Array<object>
object
inboxId
required
string format: uuid
name
required
string
type
required
string
Allowed values: sales service parts bodyshop general
leads
required
number
byInboxType
required
Array<object>
object
type
required
string
Allowed values: sales service parts bodyshop general
leads
required
number
byLocation
required
Array<object>
object
locationId
required
string format: uuid
nullable
name
required

“No location” when there is none

string
leads
required
number
byItem
required

The ten items with most leads

Array<object>
object
item
required
One of: discriminator: type
object
id
required
string format: uuid
source
required

Where the item came from: manual, csv, api or an integration key

string
externalId
required

The item’s id in its source

string
locationId
required
string format: uuid
nullable
title
required

From the attributes

string
status
required

The availability: in_stock, out_of_stock, preorder or backorder for products; an industry pack’s item types have their own

string
price
required
One of:
object
amountMinor
required

Amount in minor units (pence, cents)

number
currency
required

ISO 4217

string
billing
required

How the price is charged: one_off (once), monthly (every month) or annual (every year)

string
Allowed values: one_off monthly annual
images
required

Image links, main image first

Array<string>
archivedAt
required

When it was removed from the catalogue (no longer in stock). Removed items stay on the leads and threads that mention them

string format: date-time
nullable
url
required

Advert or product page

string
nullable
addOn
required

Usually sold as an add-on to something else (a warranty, delivery, an onboarding package). Suggestions only

boolean
addOnFor
required

The item types it is usually added to; empty means anything

Array<string>
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
attributes
required
object
title
required

Google/Meta title

string
<= 150 characters
description

Google/Meta description

string
<= 5000 characters
link

Product page. Google/Meta link

string format: uri
imageLinks

Main image first. Google/Meta image_link and additional_image_link

Array<string>
<= 11 items
price
required

Google/Meta price

object
amountMinor
required

Amount in minor units (pence, cents)

number
currency
required

ISO 4217

string
salePrice

Google/Meta sale_price

object
amountMinor
required

Amount in minor units (pence, cents)

number
currency
required

ISO 4217

string
availability

Google/Meta availability

string
default: in_stock
Allowed values: in_stock out_of_stock preorder backorder
condition

Google/Meta condition

string
default: new
Allowed values: new refurbished used
brand

Google/Meta brand

string
<= 70 characters
gtin

GTIN-8, 12, 13 or 14. Google/Meta gtin

string
mpn

Google/Meta mpn

string
<= 70 characters
sku

Your own stock code

string
<= 100 characters
googleProductCategory

Google/Meta google_product_category

string
<= 750 characters
productType

Google/Meta product_type

string
<= 750 characters
itemGroupId

Shared by variants. Google/Meta item_group_id

string
<= 50 characters
size

Google/Meta size

string
<= 100 characters
colour

Google/Meta color

string
<= 100 characters
material

Google/Meta material

string
<= 200 characters
pattern

Google/Meta pattern

string
<= 100 characters
customLabel0

Google/Meta custom_label_0

string
<= 100 characters
customLabel1

Google/Meta custom_label_1

string
<= 100 characters
customLabel2

Google/Meta custom_label_2

string
<= 100 characters
customLabel3

Google/Meta custom_label_3

string
<= 100 characters
customLabel4

Google/Meta custom_label_4

string
<= 100 characters
type
required
string
Allowed values: product
leads
required
number
byChannel
required
Array<object>
object
channel
required
string
Allowed values: email sms whatsapp chat phone form api marketplace visit messenger instagram internal
leads
required
number
byOwner
required

By the thread’s owner

Array<object>
object
userId
required

Null for threads nobody owns

string
nullable
name
required
string
leads
required
number
byCampaign
required

Most leads first; the twenty with most leads

Array<object>
object
campaignId
required

Null for leads with no campaign

string format: uuid
nullable
name
required

“No campaign” when null

string
platform
required
string
nullable
Allowed values: google microsoft meta tiktok email other
leads
required
number
previousLeads
required
number
byTrafficChannel
required
Array<object>
object
channel
required

Null for leads with no tracking (marketplaces, calls)

string
nullable
Allowed values: paid_search paid_social display email sms affiliate organic_search organic_social referral direct other
label
required
string
leads
required
number
byCompany
required

Leads by the contact’s primary company when the report is worked out (so a contact’s history moves with them), the 20 companies with most first, then “No company”

Array<object>
object
companyId
required

Null for contacts with no company

string format: uuid
nullable
name
required

“No company” when null

string
leads
required
number

Example 

{
  "range": {
    "from": "2026-09-06",
    "to": "2026-10-05",
    "days": 30,
    "preset": "today",
    "timeZone": "Europe/London",
    "granularity": "day",
    "previous": {
      "from": "2026-09-06",
      "to": "2026-10-05",
      "days": 30
    }
  },
  "bySource": [
    {
      "name": "Google Ads",
      "category": "website"
    }
  ],
  "byCategory": [
    {
      "category": "website"
    }
  ],
  "byInbox": [
    {
      "name": "Leeds Sales",
      "type": "sales"
    }
  ],
  "byInboxType": [
    {
      "type": "sales"
    }
  ],
  "byLocation": [
    {
      "name": "Leeds"
    }
  ],
  "byItem": [
    {
      "item": {
        "source": "my-dms",
        "externalId": "SKU-1042",
        "title": "Oak dining table",
        "status": "in_stock",
        "price": {
          "amountMinor": 1299500,
          "currency": "GBP"
        },
        "billing": "one_off",
        "addOnFor": [
          "product"
        ],
        "attributes": {
          "title": "Merino jumper",
          "price": {
            "amountMinor": 1299500,
            "currency": "GBP"
          },
          "salePrice": {
            "amountMinor": 1299500,
            "currency": "GBP"
          },
          "availability": "in_stock",
          "condition": "new"
        },
        "type": "product"
      }
    }
  ],
  "byChannel": [
    {
      "channel": "email"
    }
  ],
  "byOwner": [
    {
      "name": "James Patel"
    }
  ],
  "byCampaign": [
    {
      "name": "Spring sale",
      "platform": "google"
    }
  ],
  "byTrafficChannel": [
    {
      "channel": "paid_search",
      "label": "Paid search"
    }
  ],
  "byCompany": [
    {
      "name": "Acme Fleet Services"
    }
  ]
}

400

Section titled “400”

Unusable dates or filters

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

401

Section titled “401”

Missing or invalid API key

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

402

Section titled “402”

The organisation is on the Free plan (code upgrade_required)

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
feature
required

The feature that needs Pro

string
nullable
Allowed values: extraSeats connections aiAssistant aiReplies rules fullReports api inboxes bulkMessages videoMessages
upgradePath
required

Where to upgrade or pay, in the web app

string

Example 

{
  "statusCode": 402,
  "code": "upgrade_required",
  "message": "Connections are part of Pro. Upgrade to connect texts, calls and more.",
  "feature": "extraSeats",
  "upgradePath": "/settings/billing"
}

403

Section titled “403”

The key does not have the scope (or the person the permission)

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

429

Section titled “429”

Rate limit reached

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
retryAfter
required

Seconds until another request will be accepted

number

Example 

{
  "statusCode": 429,
  "code": "rate_limited",
  "message": "Too many requests. Each key can make 120 requests a minute; try again in 12 seconds.",
  "retryAfter": 12
}