> ## Documentation Index > Fetch the complete documentation index at: https://docs.findtempo.co/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/themes/{id} openapi: 3.0.0 info: title: Tempo API description: >- The Tempo API gives you programmatic access to Tempo over HTTP. Authenticate with an API key passed as a Bearer token in the `Authorization` header. If you are building an AI agent rather than a traditional integration, the [MCP server](/integrations/mcp) exposes a richer surface and handles auth over OAuth. version: '1.0' contact: {} servers: - url: https://findtempo.co description: Production security: [] tags: [] paths: /api/v1/themes/{id}: get: tags: - Public Read Tools summary: Inspect one theme or topic description: >- 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. operationId: PublicReadToolsController_getTheme_v1 parameters: - name: id in: path required: true description: >- Theme id, topic id, or "none" for unassigned themes at level topics. Merged theme ids resolve to the current theme. schema: type: string minLength: 1 maxLength: 80 - name: X-Acting-User in: header required: false description: >- 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. schema: type: string - name: level in: query required: false description: >- themes: specific recurring subjects; topics: broad areas grouping themes. schema: type: string enum: - themes - topics default: themes - name: days in: query required: false description: >- Window ending today, compared with the equal window just before. Not with from/to. schema: type: integer enum: - 7 - 30 - 90 - 365 default: 30 - name: from in: query required: false description: >- Custom window start (YYYY-MM-DD); needs to, at most 366 days, not with days. schema: type: string format: date - name: to in: query required: false description: Custom window end (YYYY-MM-DD, inclusive); needs from. schema: type: string format: date - name: sources in: query required: false description: >- Count only observations from these source groups. Comma-separated or repeated; empty is no filter. schema: type: array items: type: string enum: - calls - emails - slack - documents style: form explode: false - name: types in: query required: false description: >- Themes holding any of these observation types. Comma-separated or repeated. schema: type: array items: type: string enum: - 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 style: form explode: false - name: families in: query required: false description: >- Themes holding any type of these families. With types, only the types in both count. Comma-separated or repeated. schema: type: array items: type: string enum: - voice - health - commercial - context - craft style: form explode: false - name: deal_id in: query required: false description: >- Themes level only. Select themes raised on this deal in the window; counts stay organization-wide. schema: type: string format: uuid - name: include in: query required: false description: >- Sections to expand. Themes: topic, definition, examples, related, timeline, observations, deals, accounts, artifacts. Topics: themes, timeline, observations, deals, accounts, artifacts. Comma-separated or repeated. schema: type: array items: type: string enum: - topic - definition - examples - related - timeline - observations - deals - artifacts - accounts - themes style: form explode: false - name: granularity in: query required: false description: >- 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. schema: type: string enum: - day - week - month - name: evidence_limit in: query required: false description: >- Rows per included evidence kind. Total evidence budget is 60 rows; examples have at most 8. schema: type: integer minimum: 1 maximum: 50 default: 10 - name: evidence_cursor in: query required: false description: >- Continue one evidence page. Include exactly one of observations, deals, accounts or artifacts. schema: type: string maxLength: 64 responses: '200': description: Theme or topic returned. content: application/json: schema: $ref: '#/components/schemas/ThemeResponse' '400': description: Unknown parameter or invalid combination for the level. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' '404': description: Theme or topic not found in the window and filters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' security: - api-key: [] components: schemas: ThemeResponse: type: object required: - comparison - evidence_scope - availability - period - analyzed_account_count - previous_analyzed_account_count - analyzed_artifact_count - previous_analyzed_artifact_count - analyzed_deal_count - themes_through - level properties: search: type: object description: Present only with query. required: - mode - truncated - revision properties: mode: type: string enum: - hybrid - keyword keyword_only: type: integer description: Rows that matched by keywords only. truncated: type: boolean description: True when retrieval exceeded the internal top-100 window. revision: type: string comparison: type: string enum: - ok - unavailable description: >- unavailable: one window had too few active accounts to compare, so growth is null and nothing is escalating or declining. evidence_scope: type: string enum: - organization - your_deals description: >- your_deals: counts and rows stay organization-wide, but evidence comes only from deals the principal can access. availability: type: string enum: - ready - hidden - unpublished description: >- hidden: Themes is not enabled for the organization; unpublished: none built yet. period: type: object required: - from - to - previous_from - previous_to - days properties: from: type: string to: type: string previous_from: type: string previous_to: type: string days: type: integer analyzed_account_count: type: integer previous_analyzed_account_count: type: integer analyzed_artifact_count: type: integer previous_analyzed_artifact_count: type: integer analyzed_deal_count: type: integer themes_through: type: string nullable: true description: >- Day of the newest observation grouped into a theme, within the long-term range: where theme data ends. computed_at: type: string format: date-time description: >- 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. level: type: string enum: - themes - topics theme: allOf: - $ref: '#/components/schemas/ThemeDetail' nullable: true description: >- Present only at level themes. Null while Themes is hidden or unpublished. topic: allOf: - $ref: '#/components/schemas/TopicDetail' nullable: true description: >- Present only at level topics. Null while unavailable or topic grouping is disabled. enabled: type: boolean description: 'Topics level only: whether topic grouping is enabled.' ErrorResponseDto: type: object properties: statusCode: type: integer message: oneOf: - type: string - type: array items: type: string error: type: string errors: type: object additionalProperties: type: array items: type: string required: - statusCode - message ThemeDetail: allOf: - $ref: '#/components/schemas/ThemeRow' - type: object description: Sections appear only when requested with include. properties: topic: type: object nullable: true properties: topic_id: type: string name: type: string description: type: string definition: type: object nullable: true description: null when the theme has no definition yet. properties: shared_meaning: type: string required_concepts: type: array items: type: string exclusions: type: array items: type: string examples: type: object properties: typical_example: allOf: - $ref: '#/components/schemas/ThemeObservationRow' nullable: true others: type: array items: $ref: '#/components/schemas/ThemeObservationRow' related: type: array description: >- Themes raised on the same deals over the last 90 days ending today, in all sources, closest overlap first. items: type: object required: - theme_id - types - name - shared_deal_count properties: theme_id: type: string types: type: array items: type: string enum: - 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 name: type: string shared_deal_count: type: integer timeline: $ref: '#/components/schemas/ThemeTimeline' observations: type: object required: - items - total - next_cursor properties: items: type: array items: $ref: '#/components/schemas/ThemeObservationRow' total: type: integer next_cursor: type: string nullable: true description: Pass as evidence_cursor to continue this one kind. deals: type: object required: - items - total - next_cursor properties: items: type: array items: $ref: '#/components/schemas/ThemeDealRow' total: type: integer next_cursor: type: string nullable: true description: Pass as evidence_cursor to continue this one kind. artifacts: type: object required: - items - total - next_cursor properties: items: type: array items: $ref: '#/components/schemas/ThemeArtifactRow' total: type: integer next_cursor: type: string nullable: true description: Pass as evidence_cursor to continue this one kind. accounts: type: object required: - items - total - next_cursor properties: items: type: array items: $ref: '#/components/schemas/ThemeAccountRow' total: type: integer next_cursor: type: string nullable: true description: Pass as evidence_cursor to continue this one kind. TopicDetail: allOf: - $ref: '#/components/schemas/TopicRow' - type: object description: Sections appear only when requested with include. properties: themes_total: type: integer description: Eligible child themes before the preview cap. themes_truncated: type: boolean description: True for a partial preview. themes: type: array description: Up to 20 eligible child themes, most accounts first. items: type: object required: - theme_id - name - types - status - account_count - deal_count properties: theme_id: type: string name: type: string types: type: array items: type: string enum: - 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 status: type: string enum: - new - escalating - steady - declining - no_baseline - quiet account_count: type: integer deal_count: type: integer timeline: $ref: '#/components/schemas/ThemeTimeline' observations: type: object required: - items - total - next_cursor properties: items: type: array items: $ref: '#/components/schemas/ThemeObservationRow' total: type: integer next_cursor: type: string nullable: true description: Pass as evidence_cursor to continue this one kind. deals: type: object required: - items - total - next_cursor properties: items: type: array items: $ref: '#/components/schemas/ThemeDealRow' total: type: integer next_cursor: type: string nullable: true description: Pass as evidence_cursor to continue this one kind. artifacts: type: object required: - items - total - next_cursor properties: items: type: array items: $ref: '#/components/schemas/ThemeArtifactRow' total: type: integer next_cursor: type: string nullable: true description: Pass as evidence_cursor to continue this one kind. accounts: type: object required: - items - total - next_cursor properties: items: type: array items: $ref: '#/components/schemas/ThemeAccountRow' total: type: integer next_cursor: type: string nullable: true description: Pass as evidence_cursor to continue this one kind. ThemeRow: allOf: - $ref: '#/components/schemas/ThemeMetrics' - type: object required: - theme_id - topic_id properties: theme_id: type: string topic_id: type: string nullable: true description: Parent topic; null when unassigned or when topics are off. deal_observation_count: type: integer description: 'Only with deal_id: observations on that deal.' ThemeObservationRow: type: object required: - observation_id - observation_text - artifact_id - artifact_title - artifact_type - source_group - deal_id - deal_name - occurred_at properties: observation_id: type: string observation_text: type: string description: A paraphrased summary, not a verbatim quote. type: type: string enum: - 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 artifact_id: type: string artifact_title: type: string nullable: true artifact_type: type: string nullable: true source_group: type: string enum: - calls - emails - slack - documents deal_id: type: string deal_name: type: string nullable: true occurred_at: type: string nullable: true ThemeTimeline: type: object required: - granularity - buckets - by_source properties: granularity: type: string enum: - day - week - month buckets: type: array description: >- Every bucket of the window, oldest first; the first and last can be partial. items: type: object required: - start - end - observation_count - artifact_count - account_count - analyzed_account_count - analyzed_artifact_count - occurrence_share properties: start: type: string end: type: string description: Last day of the bucket, inclusive. observation_count: type: integer artifact_count: type: integer account_count: type: integer deal_count: type: integer analyzed_account_count: type: integer analyzed_artifact_count: type: integer occurrence_share: type: number nullable: true description: account_count / analyzed_account_count; null when none. by_source: type: array items: type: object required: - source - observation_count - artifact_count - account_count - deal_count properties: source: type: string enum: - calls - emails - slack - documents observation_count: type: integer artifact_count: type: integer account_count: type: integer deal_count: type: integer ThemeDealRow: type: object required: - deal_id - deal_name - observation_count - artifact_count - last_seen_at properties: deal_id: type: string deal_name: type: string nullable: true observation_count: type: integer artifact_count: type: integer last_seen_at: type: string nullable: true ThemeArtifactRow: type: object required: - artifact_id - artifact_title - artifact_type - source_group - deal_id - deal_name - occurred_at - observation_count - excerpt properties: artifact_id: type: string artifact_title: type: string nullable: true artifact_type: type: string nullable: true source_group: type: string enum: - calls - emails - slack - documents deal_id: type: string deal_name: type: string nullable: true occurred_at: type: string nullable: true observation_count: type: integer excerpt: type: string description: A paraphrased summary of one of the artifact's observations. ThemeAccountRow: type: object required: - account_id - name - deal_count - observation_count - last_seen_at properties: account_id: type: string name: type: string nullable: true deal_count: type: integer observation_count: type: integer last_seen_at: type: string nullable: true TopicRow: allOf: - $ref: '#/components/schemas/ThemeMetrics' - type: object required: - topic_id - theme_count properties: topic_id: type: string theme_count: type: integer description: >- Themes matching the filters and seen in the selected sources by the window end. ThemeMetrics: type: object required: - types - families - name - description - status - observation_count - artifact_count - deal_count - account_count - previous_observation_count - previous_artifact_count - previous_deal_count - previous_account_count - all_time_observation_count - all_time_deal_count - all_time_account_count - occurrence_share - previous_occurrence_share - growth_points - first_seen_at - last_seen_at - change properties: types: type: array items: type: string enum: - 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 description: Observation types of the current members, most first. families: type: array items: type: string enum: - voice - health - commercial - context - craft name: type: string description: type: string status: type: string enum: - new - escalating - steady - declining - no_baseline - quiet description: >- new: first seen in the window, with no observations earlier in the long-term range (see all_time_observation_count). escalating/declining: occurrence share moved 25% or more with at least 3 accounts in one window. steady. no_baseline: comparison unavailable. quiet: seen in that long-term range, but not in either window. observation_count: type: integer artifact_count: type: integer deal_count: type: integer account_count: type: integer previous_observation_count: type: integer previous_artifact_count: type: integer previous_deal_count: type: integer previous_account_count: type: integer all_time_observation_count: type: integer description: >- Over the last 90 days through the period's last day (or the period and the one before it, when they span more), in all sources. The name predates the range. all_time_deal_count: type: integer description: >- Over the last 90 days through the period's last day (or the period and the one before it, when they span more), in all sources. The name predates the range. all_time_account_count: type: integer description: >- Over the last 90 days through the period's last day (or the period and the one before it, when they span more), in all sources. The name predates the range. occurrence_share: type: number nullable: true description: >- 0 to 1 share of the window's active accounts that hold it; null when none were analyzed. previous_occurrence_share: type: number nullable: true growth_points: type: number nullable: true description: >- Percentage-point change of occurrence share; null when comparison is unavailable. first_seen_at: type: string nullable: true description: >- Day of the first observation over the last 90 days through the period's last day (or the period and the one before it, when they span more), in all sources. last_seen_at: type: string nullable: true description: >- Day of the latest observation over the last 90 days through the period's last day (or the period and the one before it, when they span more), in all sources. change: type: object required: - observation_delta - deal_delta - account_delta properties: observation_delta: type: integer deal_delta: type: integer account_delta: type: integer securitySchemes: api-key: type: http scheme: bearer description: >- Your organization API key. Paste the key itself — the "Bearer " prefix is added for you. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.