Inspect one theme or topic

curl --request GET \
  --url https://findtempo.co/api/v1/themes/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://findtempo.co/api/v1/themes/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://findtempo.co/api/v1/themes/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://findtempo.co/api/v1/themes/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://findtempo.co/api/v1/themes/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "comparison": "ok",
  "evidence_scope": "organization",
  "availability": "ready",
  "period": {
    "from": "<string>",
    "to": "<string>",
    "previous_from": "<string>",
    "previous_to": "<string>",
    "days": 123
  },
  "analyzed_account_count": 123,
  "previous_analyzed_account_count": 123,
  "analyzed_artifact_count": 123,
  "previous_analyzed_artifact_count": 123,
  "analyzed_deal_count": 123,
  "themes_through": "<string>",
  "level": "themes",
  "search": {
    "mode": "hybrid",
    "truncated": true,
    "revision": "<string>",
    "keyword_only": 123
  },
  "computed_at": "2023-11-07T05:31:56Z",
  "theme": {
    "types": [
      "questions"
    ],
    "families": [
      "voice"
    ],
    "name": "<string>",
    "description": "<string>",
    "status": "new",
    "observation_count": 123,
    "artifact_count": 123,
    "deal_count": 123,
    "account_count": 123,
    "previous_observation_count": 123,
    "previous_artifact_count": 123,
    "previous_deal_count": 123,
    "previous_account_count": 123,
    "all_time_observation_count": 123,
    "all_time_deal_count": 123,
    "all_time_account_count": 123,
    "occurrence_share": 123,
    "previous_occurrence_share": 123,
    "growth_points": 123,
    "first_seen_at": "<string>",
    "last_seen_at": "<string>",
    "change": {
      "observation_delta": 123,
      "deal_delta": 123,
      "account_delta": 123
    },
    "theme_id": "<string>",
    "topic_id": "<string>",
    "deal_observation_count": 123,
    "topic": {
      "topic_id": "<string>",
      "name": "<string>",
      "description": "<string>"
    },
    "definition": {
      "shared_meaning": "<string>",
      "required_concepts": [
        "<string>"
      ],
      "exclusions": [
        "<string>"
      ]
    },
    "examples": {
      "typical_example": {
        "observation_id": "<string>",
        "observation_text": "<string>",
        "artifact_id": "<string>",
        "artifact_title": "<string>",
        "artifact_type": "<string>",
        "source_group": "calls",
        "deal_id": "<string>",
        "deal_name": "<string>",
        "occurred_at": "<string>",
        "type": "questions"
      },
      "others": [
        {
          "observation_id": "<string>",
          "observation_text": "<string>",
          "artifact_id": "<string>",
          "artifact_title": "<string>",
          "artifact_type": "<string>",
          "source_group": "calls",
          "deal_id": "<string>",
          "deal_name": "<string>",
          "occurred_at": "<string>",
          "type": "questions"
        }
      ]
    },
    "related": [
      {
        "theme_id": "<string>",
        "types": [
          "questions"
        ],
        "name": "<string>",
        "shared_deal_count": 123
      }
    ],
    "timeline": {
      "granularity": "day",
      "buckets": [
        {
          "start": "<string>",
          "end": "<string>",
          "observation_count": 123,
          "artifact_count": 123,
          "account_count": 123,
          "analyzed_account_count": 123,
          "analyzed_artifact_count": 123,
          "occurrence_share": 123,
          "deal_count": 123
        }
      ],
      "by_source": [
        {
          "source": "calls",
          "observation_count": 123,
          "artifact_count": 123,
          "account_count": 123,
          "deal_count": 123
        }
      ]
    },
    "observations": {
      "items": [
        {
          "observation_id": "<string>",
          "observation_text": "<string>",
          "artifact_id": "<string>",
          "artifact_title": "<string>",
          "artifact_type": "<string>",
          "source_group": "calls",
          "deal_id": "<string>",
          "deal_name": "<string>",
          "occurred_at": "<string>",
          "type": "questions"
        }
      ],
      "total": 123,
      "next_cursor": "<string>"
    },
    "deals": {
      "items": [
        {
          "deal_id": "<string>",
          "deal_name": "<string>",
          "observation_count": 123,
          "artifact_count": 123,
          "last_seen_at": "<string>"
        }
      ],
      "total": 123,
      "next_cursor": "<string>"
    },
    "artifacts": {
      "items": [
        {
          "artifact_id": "<string>",
          "artifact_title": "<string>",
          "artifact_type": "<string>",
          "source_group": "calls",
          "deal_id": "<string>",
          "deal_name": "<string>",
          "occurred_at": "<string>",
          "observation_count": 123,
          "excerpt": "<string>"
        }
      ],
      "total": 123,
      "next_cursor": "<string>"
    },
    "accounts": {
      "items": [
        {
          "account_id": "<string>",
          "name": "<string>",
          "deal_count": 123,
          "observation_count": 123,
          "last_seen_at": "<string>"
        }
      ],
      "total": 123,
      "next_cursor": "<string>"
    }
  },
  "topic": {
    "types": [
      "questions"
    ],
    "families": [
      "voice"
    ],
    "name": "<string>",
    "description": "<string>",
    "status": "new",
    "observation_count": 123,
    "artifact_count": 123,
    "deal_count": 123,
    "account_count": 123,
    "previous_observation_count": 123,
    "previous_artifact_count": 123,
    "previous_deal_count": 123,
    "previous_account_count": 123,
    "all_time_observation_count": 123,
    "all_time_deal_count": 123,
    "all_time_account_count": 123,
    "occurrence_share": 123,
    "previous_occurrence_share": 123,
    "growth_points": 123,
    "first_seen_at": "<string>",
    "last_seen_at": "<string>",
    "change": {
      "observation_delta": 123,
      "deal_delta": 123,
      "account_delta": 123
    },
    "topic_id": "<string>",
    "theme_count": 123,
    "themes_total": 123,
    "themes_truncated": true,
    "themes": [
      {
        "theme_id": "<string>",
        "name": "<string>",
        "types": [
          "questions"
        ],
        "status": "new",
        "account_count": 123,
        "deal_count": 123
      }
    ],
    "timeline": {
      "granularity": "day",
      "buckets": [
        {
          "start": "<string>",
          "end": "<string>",
          "observation_count": 123,
          "artifact_count": 123,
          "account_count": 123,
          "analyzed_account_count": 123,
          "analyzed_artifact_count": 123,
          "occurrence_share": 123,
          "deal_count": 123
        }
      ],
      "by_source": [
        {
          "source": "calls",
          "observation_count": 123,
          "artifact_count": 123,
          "account_count": 123,
          "deal_count": 123
        }
      ]
    },
    "observations": {
      "items": [
        {
          "observation_id": "<string>",
          "observation_text": "<string>",
          "artifact_id": "<string>",
          "artifact_title": "<string>",
          "artifact_type": "<string>",
          "source_group": "calls",
          "deal_id": "<string>",
          "deal_name": "<string>",
          "occurred_at": "<string>",
          "type": "questions"
        }
      ],
      "total": 123,
      "next_cursor": "<string>"
    },
    "deals": {
      "items": [
        {
          "deal_id": "<string>",
          "deal_name": "<string>",
          "observation_count": 123,
          "artifact_count": 123,
          "last_seen_at": "<string>"
        }
      ],
      "total": 123,
      "next_cursor": "<string>"
    },
    "artifacts": {
      "items": [
        {
          "artifact_id": "<string>",
          "artifact_title": "<string>",
          "artifact_type": "<string>",
          "source_group": "calls",
          "deal_id": "<string>",
          "deal_name": "<string>",
          "occurred_at": "<string>",
          "observation_count": 123,
          "excerpt": "<string>"
        }
      ],
      "total": 123,
      "next_cursor": "<string>"
    },
    "accounts": {
      "items": [
        {
          "account_id": "<string>",
          "name": "<string>",
          "deal_count": 123,
          "observation_count": 123,
          "last_seen_at": "<string>"
        }
      ],
      "total": 123,
      "next_cursor": "<string>"
    }
  },
  "enabled": true
}

{
  "statusCode": 123,
  "message": "<string>",
  "error": "<string>",
  "errors": {}
}

{
  "statusCode": 123,
  "message": "<string>",
  "error": "<string>",
  "errors": {}
}

Themes

Inspect one theme or topic

Reads one theme or topic by the id a GET /themes row carries, with the same parameters and payload as the MCP get_theme tool. Defaults to a compact theme over the last 30 days; pass level=topics for a topic id. include expands sections (topic, definition, examples, related, timeline, observations, deals, artifacts, accounts; themes for a topic), comma-separated. Evidence sections share a 60-row budget per call, sized by evidence_limit, and page one kind at a time with evidence_cursor. An unknown or filtered-out id returns 404 while Themes are ready; null while hidden or unpublished.

GET

api

themes

{id}

Inspect one theme or topic

curl --request GET \
  --url https://findtempo.co/api/v1/themes/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://findtempo.co/api/v1/themes/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://findtempo.co/api/v1/themes/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://findtempo.co/api/v1/themes/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://findtempo.co/api/v1/themes/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "comparison": "ok",
  "evidence_scope": "organization",
  "availability": "ready",
  "period": {
    "from": "<string>",
    "to": "<string>",
    "previous_from": "<string>",
    "previous_to": "<string>",
    "days": 123
  },
  "analyzed_account_count": 123,
  "previous_analyzed_account_count": 123,
  "analyzed_artifact_count": 123,
  "previous_analyzed_artifact_count": 123,
  "analyzed_deal_count": 123,
  "themes_through": "<string>",
  "level": "themes",
  "search": {
    "mode": "hybrid",
    "truncated": true,
    "revision": "<string>",
    "keyword_only": 123
  },
  "computed_at": "2023-11-07T05:31:56Z",
  "theme": {
    "types": [
      "questions"
    ],
    "families": [
      "voice"
    ],
    "name": "<string>",
    "description": "<string>",
    "status": "new",
    "observation_count": 123,
    "artifact_count": 123,
    "deal_count": 123,
    "account_count": 123,
    "previous_observation_count": 123,
    "previous_artifact_count": 123,
    "previous_deal_count": 123,
    "previous_account_count": 123,
    "all_time_observation_count": 123,
    "all_time_deal_count": 123,
    "all_time_account_count": 123,
    "occurrence_share": 123,
    "previous_occurrence_share": 123,
    "growth_points": 123,
    "first_seen_at": "<string>",
    "last_seen_at": "<string>",
    "change": {
      "observation_delta": 123,
      "deal_delta": 123,
      "account_delta": 123
    },
    "theme_id": "<string>",
    "topic_id": "<string>",
    "deal_observation_count": 123,
    "topic": {
      "topic_id": "<string>",
      "name": "<string>",
      "description": "<string>"
    },
    "definition": {
      "shared_meaning": "<string>",
      "required_concepts": [
        "<string>"
      ],
      "exclusions": [
        "<string>"
      ]
    },
    "examples": {
      "typical_example": {
        "observation_id": "<string>",
        "observation_text": "<string>",
        "artifact_id": "<string>",
        "artifact_title": "<string>",
        "artifact_type": "<string>",
        "source_group": "calls",
        "deal_id": "<string>",
        "deal_name": "<string>",
        "occurred_at": "<string>",
        "type": "questions"
      },
      "others": [
        {
          "observation_id": "<string>",
          "observation_text": "<string>",
          "artifact_id": "<string>",
          "artifact_title": "<string>",
          "artifact_type": "<string>",
          "source_group": "calls",
          "deal_id": "<string>",
          "deal_name": "<string>",
          "occurred_at": "<string>",
          "type": "questions"
        }
      ]
    },
    "related": [
      {
        "theme_id": "<string>",
        "types": [
          "questions"
        ],
        "name": "<string>",
        "shared_deal_count": 123
      }
    ],
    "timeline": {
      "granularity": "day",
      "buckets": [
        {
          "start": "<string>",
          "end": "<string>",
          "observation_count": 123,
          "artifact_count": 123,
          "account_count": 123,
          "analyzed_account_count": 123,
          "analyzed_artifact_count": 123,
          "occurrence_share": 123,
          "deal_count": 123
        }
      ],
      "by_source": [
        {
          "source": "calls",
          "observation_count": 123,
          "artifact_count": 123,
          "account_count": 123,
          "deal_count": 123
        }
      ]
    },
    "observations": {
      "items": [
        {
          "observation_id": "<string>",
          "observation_text": "<string>",
          "artifact_id": "<string>",
          "artifact_title": "<string>",
          "artifact_type": "<string>",
          "source_group": "calls",
          "deal_id": "<string>",
          "deal_name": "<string>",
          "occurred_at": "<string>",
          "type": "questions"
        }
      ],
      "total": 123,
      "next_cursor": "<string>"
    },
    "deals": {
      "items": [
        {
          "deal_id": "<string>",
          "deal_name": "<string>",
          "observation_count": 123,
          "artifact_count": 123,
          "last_seen_at": "<string>"
        }
      ],
      "total": 123,
      "next_cursor": "<string>"
    },
    "artifacts": {
      "items": [
        {
          "artifact_id": "<string>",
          "artifact_title": "<string>",
          "artifact_type": "<string>",
          "source_group": "calls",
          "deal_id": "<string>",
          "deal_name": "<string>",
          "occurred_at": "<string>",
          "observation_count": 123,
          "excerpt": "<string>"
        }
      ],
      "total": 123,
      "next_cursor": "<string>"
    },
    "accounts": {
      "items": [
        {
          "account_id": "<string>",
          "name": "<string>",
          "deal_count": 123,
          "observation_count": 123,
          "last_seen_at": "<string>"
        }
      ],
      "total": 123,
      "next_cursor": "<string>"
    }
  },
  "topic": {
    "types": [
      "questions"
    ],
    "families": [
      "voice"
    ],
    "name": "<string>",
    "description": "<string>",
    "status": "new",
    "observation_count": 123,
    "artifact_count": 123,
    "deal_count": 123,
    "account_count": 123,
    "previous_observation_count": 123,
    "previous_artifact_count": 123,
    "previous_deal_count": 123,
    "previous_account_count": 123,
    "all_time_observation_count": 123,
    "all_time_deal_count": 123,
    "all_time_account_count": 123,
    "occurrence_share": 123,
    "previous_occurrence_share": 123,
    "growth_points": 123,
    "first_seen_at": "<string>",
    "last_seen_at": "<string>",
    "change": {
      "observation_delta": 123,
      "deal_delta": 123,
      "account_delta": 123
    },
    "topic_id": "<string>",
    "theme_count": 123,
    "themes_total": 123,
    "themes_truncated": true,
    "themes": [
      {
        "theme_id": "<string>",
        "name": "<string>",
        "types": [
          "questions"
        ],
        "status": "new",
        "account_count": 123,
        "deal_count": 123
      }
    ],
    "timeline": {
      "granularity": "day",
      "buckets": [
        {
          "start": "<string>",
          "end": "<string>",
          "observation_count": 123,
          "artifact_count": 123,
          "account_count": 123,
          "analyzed_account_count": 123,
          "analyzed_artifact_count": 123,
          "occurrence_share": 123,
          "deal_count": 123
        }
      ],
      "by_source": [
        {
          "source": "calls",
          "observation_count": 123,
          "artifact_count": 123,
          "account_count": 123,
          "deal_count": 123
        }
      ]
    },
    "observations": {
      "items": [
        {
          "observation_id": "<string>",
          "observation_text": "<string>",
          "artifact_id": "<string>",
          "artifact_title": "<string>",
          "artifact_type": "<string>",
          "source_group": "calls",
          "deal_id": "<string>",
          "deal_name": "<string>",
          "occurred_at": "<string>",
          "type": "questions"
        }
      ],
      "total": 123,
      "next_cursor": "<string>"
    },
    "deals": {
      "items": [
        {
          "deal_id": "<string>",
          "deal_name": "<string>",
          "observation_count": 123,
          "artifact_count": 123,
          "last_seen_at": "<string>"
        }
      ],
      "total": 123,
      "next_cursor": "<string>"
    },
    "artifacts": {
      "items": [
        {
          "artifact_id": "<string>",
          "artifact_title": "<string>",
          "artifact_type": "<string>",
          "source_group": "calls",
          "deal_id": "<string>",
          "deal_name": "<string>",
          "occurred_at": "<string>",
          "observation_count": 123,
          "excerpt": "<string>"
        }
      ],
      "total": 123,
      "next_cursor": "<string>"
    },
    "accounts": {
      "items": [
        {
          "account_id": "<string>",
          "name": "<string>",
          "deal_count": 123,
          "observation_count": 123,
          "last_seen_at": "<string>"
        }
      ],
      "total": 123,
      "next_cursor": "<string>"
    }
  },
  "enabled": true
}

{
  "statusCode": 123,
  "message": "<string>",
  "error": "<string>",
  "errors": {}
}

{
  "statusCode": 123,
  "message": "<string>",
  "error": "<string>",
  "errors": {}
}

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.

Path Parameters

string

required

Theme id, topic id, or "none" for unassigned themes at level topics. Merged theme ids resolve to the current theme.

Required string length: 1 - 80

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.

Available options:

7,

30,

90,

365

from

string<date>

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

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.

include

enum<string>[]

Sections to expand. Themes: topic, definition, examples, related, timeline, observations, deals, accounts, artifacts. Topics: themes, timeline, observations, deals, accounts, artifacts. Comma-separated or repeated.

Available options:

topic,

definition,

examples,

related,

timeline,

observations,

deals,

artifacts,

accounts,

themes

granularity

enum<string>

Requires include=timeline. Default day up to 14 days, week up to about a quarter, month beyond. day supports at most 92 days; at most 150 buckets per call.

Available options:

day,

week,

month

evidence_limit

integer

default:10

Rows per included evidence kind. Total evidence budget is 60 rows; examples have at most 8.

Required range: 1 <= x <= 50

evidence_cursor

string

Continue one evidence page. Include exactly one of observations, deals, accounts or artifacts.

Maximum string length: 64

Response

Theme or topic 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

Show child attributes

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

object

Present only with query.

Show child attributes

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.

theme

object | null

Present only at level themes. Null while Themes is hidden or unpublished.

Show child attributes

topic

object | null

Present only at level topics. Null while unavailable or topic grouping is disabled.

Show child attributes

enabled

boolean

Topics level only: whether topic grouping is enabled.

Getting Started

MCP

REST API

Inspect one theme or topic

Authorizations

Headers

Path Parameters

Query Parameters

Response