Skip to main content
GET
List recurring themes or topics across organization deals

Authorizations

Authorization
string
header
required

Your organization API key. Paste the key itself — the "Bearer " prefix is added for you.

Headers

X-Acting-User
string

Run the request as this organization member (user id or email). Omit to run as the organization. A value that is not a member returns 403.

Query Parameters

level
enum<string>
default:themes

themes: specific recurring subjects; topics: broad areas grouping themes.

Available options:
themes,
topics
days
enum<integer>
default:30

Window ending today, compared with the equal window just before. Not with from/to. Defaults to 30; a query without a window, status filter, or growth sort defaults to 365.

Available options:
7,
30,
90,
365
from
string<date>

Custom window start (YYYY-MM-DD); needs to, at most 366 days, not with days.

to
string<date>

Custom window end (YYYY-MM-DD, inclusive); needs from.

sources
enum<string>[]

Count only observations from these source groups. Comma-separated or repeated; empty is no filter.

Available options:
calls,
emails,
slack,
documents
types
enum<string>[]

Themes holding any of these observation types. Comma-separated or repeated.

Available options:
questions,
discovery,
pain,
risk,
objection,
product_request,
requirement,
pricing_signal,
timeline,
urgency,
commitment,
buying_intent,
product_information,
commercial_information,
implementation_information,
stakeholder_signal,
competitor_signal,
risk_resolution,
seller_intent,
coaching,
background,
summary
families
enum<string>[]

Themes holding any type of these families. With types, only the types in both count. Comma-separated or repeated.

Available options:
voice,
health,
commercial,
context,
craft
deal_id
string<uuid>

Themes level only. Select themes raised on this deal in the window; counts stay organization-wide.

statuses
enum<string>[]

Select rows by status at the chosen level. Comma-separated or repeated.

Available options:
new,
escalating,
steady,
declining,
no_baseline,
quiet
query
string

Hybrid relevance search; overrides sort. Bounded nearest matches, not proof of occurrence or absence.

Required string length: 1 - 500
topic_id
string

Themes level only. Children of this topic id, or "none" for unassigned themes.

Maximum string length: 80
sort
enum<string>
default:occurrence

Browse order. Query always ranks by relevance.

Available options:
occurrence,
growth,
observations,
artifacts,
deals,
accounts,
name,
status,
first_seen,
last_seen
direction
enum<string>

Browse direction: desc by default; asc for name and status.

Available options:
asc,
desc
limit
integer
default:25

Rows per page.

Required range: 1 <= x <= 50
cursor
string

next_cursor from the previous page; repeat the same filters, query and sort.

Maximum string length: 64

Response

Themes or topics returned.

comparison
enum<string>
required

unavailable: one window had too few active accounts to compare, so growth is null and nothing is escalating or declining.

Available options:
ok,
unavailable
evidence_scope
enum<string>
required

your_deals: counts and rows stay organization-wide, but evidence comes only from deals the principal can access.

Available options:
organization,
your_deals
availability
enum<string>
required

hidden: Themes is not enabled for the organization; unpublished: none built yet.

Available options:
ready,
hidden,
unpublished
period
object
required
analyzed_account_count
integer
required
previous_analyzed_account_count
integer
required
analyzed_artifact_count
integer
required
previous_analyzed_artifact_count
integer
required
analyzed_deal_count
integer
required
themes_through
string | null
required

Day of the newest observation grouped into a theme, within the long-term range: where theme data ends.

level
enum<string>
required
Available options:
themes,
topics
status_counts
object
required

Rows at the selected level per status, before query ranking and status selection.

total
integer
required

Eligible rows at the selected level; with query, rows within the bounded top-100 retrieval window.

next_cursor
string | null
required

Pass as cursor for the next page; null on the last one.

Present only with query.

computed_at
string<date-time>

When these counts were computed (UTC). The first page of a list without query or deal_id can be up to six hours old; later pages, searches, deal_id lists, and single theme or topic reads are computed for the call.

themes
object[]

Present only at level themes.

topics
object[]

Present only at level topics.

enabled
boolean

Topics level only: false while topic grouping is disabled.

unassigned
object | null

Topics level only: compact row for unassigned themes with topic_id "none"; null with query or when none match.