> ## 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. # List recurring themes or topics across organization deals > Browses or searches the recurring subjects Tempo clusters from observations across the organization, with the same parameters and payload as the MCP search_themes tool. Defaults match MCP: level themes, the last 30 days compared with the equal window before, 25 rows by occurrence (5 by relevance with query). Counts and trends are organization-wide; evidence follows the API principal. Comma-separated values are accepted for sources, types, families and statuses. Pass level=topics for broad areas, topic_id to drill into one, deal_id for themes raised on one deal, and statuses=new,escalating or sort=growth for trends. Inspect one row with GET /themes/{id}. Only useful once Themes is enabled for the organization; check availability in the response. ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/themes 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: get: tags: - Public Read Tools summary: List recurring themes or topics across organization deals description: >- Browses or searches the recurring subjects Tempo clusters from observations across the organization, with the same parameters and payload as the MCP search_themes tool. Defaults match MCP: level themes, the last 30 days compared with the equal window before, 25 rows by occurrence (5 by relevance with query). Counts and trends are organization-wide; evidence follows the API principal. Comma-separated values are accepted for sources, types, families and statuses. Pass level=topics for broad areas, topic_id to drill into one, deal_id for themes raised on one deal, and statuses=new,escalating or sort=growth for trends. Inspect one row with GET /themes/{id}. Only useful once Themes is enabled for the organization; check availability in the response. operationId: PublicReadToolsController_listThemes_v1 parameters: - 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. Defaults to 30; a query without a window, status filter, or growth sort defaults to 365. 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: statuses in: query required: false description: >- Select rows by status at the chosen level. Comma-separated or repeated. schema: type: array items: type: string enum: - new - escalating - steady - declining - no_baseline - quiet style: form explode: false - name: query in: query required: false description: >- Hybrid relevance search; overrides sort. Bounded nearest matches, not proof of occurrence or absence. schema: type: string minLength: 1 maxLength: 500 - name: topic_id in: query required: false description: >- Themes level only. Children of this topic id, or "none" for unassigned themes. schema: type: string maxLength: 80 - name: sort in: query required: false description: Browse order. Query always ranks by relevance. schema: type: string enum: - occurrence - growth - observations - artifacts - deals - accounts - name - status - first_seen - last_seen default: occurrence - name: direction in: query required: false description: 'Browse direction: desc by default; asc for name and status.' schema: type: string enum: - asc - desc - name: limit in: query required: false description: Rows per page. schema: type: integer minimum: 1 maximum: 50 default: 25 - name: cursor in: query required: false description: >- next_cursor from the previous page; repeat the same filters, query and sort. schema: type: string maxLength: 64 responses: '200': description: Themes or topics returned. content: application/json: schema: $ref: '#/components/schemas/ThemesListResponse' '400': description: Unknown parameter or invalid combination for the level. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' security: - api-key: [] components: schemas: ThemesListResponse: 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 - status_counts - total - next_cursor 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 status_counts: type: object additionalProperties: type: integer description: >- Rows at the selected level per status, before query ranking and status selection. themes: type: array items: $ref: '#/components/schemas/ThemeRow' description: Present only at level themes. topics: type: array items: $ref: '#/components/schemas/TopicRow' description: Present only at level topics. enabled: type: boolean description: 'Topics level only: false while topic grouping is disabled.' unassigned: allOf: - $ref: '#/components/schemas/TopicRow' nullable: true description: >- Topics level only: compact row for unassigned themes with topic_id "none"; null with query or when none match. total: type: integer description: >- Eligible rows at the selected level; with query, rows within the bounded top-100 retrieval window. next_cursor: type: string nullable: true description: Pass as cursor for the next page; null on the last one. 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 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.' 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.