Threads by tag

GET

/v1/reports/tags

const url = 'https://api.threadkite.app/v1/reports/tags?preset=today&granularity=day&inboxType=sales&sourceCategory=website&channel=email&trafficChannel=paid_search&touch=first';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

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

Threads a contact wrote in during the period (leads or not), how many carry each tag, and how many of those were won or lost. Part of Pro.

Authorizations

api_key
reports:read

Parameters

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

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

Responses

200

application/json

object

range

required

object

from

required

string format: date

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

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

threads

required

Threads a contact wrote in during the period

number

untagged

required

number

tags

required

Most used first

Array<object>

object

tagId

required

string format: uuid

name

required

string

colour

required

string

archived

required

boolean

threads

required

number

previousThreads

required

number

won

required

number

lost

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
    }
  },
  "tags": [
    {
      "colour": "blue"
    }
  ]
}

400

Unusable dates or filters

application/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

Missing or invalid API key

application/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

The organisation is on the Free plan (code upgrade_required)

application/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

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

application/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

Rate limit reached

application/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
}