> ## Documentation Index > Fetch the complete documentation index at: https://docs.omni.co/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve a topic > Retrieves a topic in a model by name. ## OpenAPI ````yaml /api/openapi.yaml get /v1/models/{modelId}/topic/{topicName} openapi: 3.1.0 info: title: Omni API description: > The Omni REST API provides programmatic access to your Omni instance for managing users, documents, queries, schedules, and more. version: 1.0.0 contact: name: Omni Support url: https://docs.omni.co servers: - url: https://{instance}.omniapp.co/api description: Production variables: instance: default: blobsrus description: Your production Omni instance subdomain - url: https://{instance}.playground.exploreomni.dev/api description: Playground variables: instance: default: blobsrus description: Your playground Omni instance subdomain security: - bearerAuth: [] - orgApiKey: [] tags: - name: AI description: AI-powered query generation - name: API Tokens description: >- Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth grants) - name: Connections description: Manage database connections - name: Connection environments description: Manage connection environments database connections - name: Content description: Unified content retrieval (documents and folders) - name: Content migration description: Export and import dashboards - name: Content validator description: Validate content against models and perform find/replace operations - name: Dashboard downloads description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files - name: Dashboard filters and controls description: Read and update dashboard filter and control default values - name: dbt description: Manage dbt configuration for connections - name: Documents description: Create, retrieve, and manage documents - name: Document favorites description: Favorite and unfavorite documents - name: Document labels description: Apply and manage labels on documents - name: Document permissions description: Manage document-level access - name: Labels description: > Manage labels in an organization. Labels can be applied to documents and folders to help organize and categorize content. **Label types:** - **Basic labels**: Can be created and managed by any user - **Verified labels**: Indicate curated or officially sanctioned content. Admin-only. - **Homepage labels**: Appear on the organization homepage. Admin-only. - name: Folders description: Create and organize content folders - name: Folder permissions description: Manage folder-level access - name: Jobs description: Check status of asynchronous jobs - name: Models description: Create and manage data models - name: Model branches description: Manage model branches and merge changes - name: Model git configuration description: Manage git configuration for shared models - name: Queries description: Execute workbook queries - name: Schedules description: Create and manage scheduled tasks - name: Schedule recipients description: Manage schedule recipients - name: Schema refresh schedules description: Manage automated schema refresh schedules for connections - name: Topics description: Retrieve topic information from models - name: Uploads description: Manage file uploads - name: Users description: Manage users - name: User attributes description: Manage user attribute definitions - name: User groups description: Manage user groups - name: User model roles description: Manage model and connection role assignments for users - name: User group model roles description: Manage model and connection role assignments for user groups - name: Uploads description: Manage CSV and spreadsheet uploads paths: /v1/models/{modelId}/topic/{topicName}: get: tags: - Topics summary: Retrieve a topic description: Retrieves a topic in a model by name. operationId: getTopic parameters: - name: modelId in: path required: true schema: type: string format: uuid description: The unique identifier of the model that contains the topic. - name: topicName in: path required: true schema: type: string description: The name of the topic. responses: '200': description: '' content: application/json: schema: type: object properties: success: type: boolean description: Indicates the request was successful topic: type: object description: >- Details about the topic. The properties included in the response will typically mirror the [IDE parameters](/modeling/topics/parameters) for topic files. properties: name: type: string description: The name of the topic base_view_name: type: string description: The name of the base view for the topic label: type: string description: The display label for the topic default_filters: type: object description: Default filters applied to the topic join_via_map: type: object description: >- Join path mappings for the topic. Keys are view names, values are arrays of view names representing the join path. additionalProperties: type: array items: type: string join_via_map_key_order: type: array items: type: string description: Order of join path keys ignored_props: type: array items: type: string description: Properties to ignore always_where_filters: type: object description: > Filters that applied to all rows in a query. In the model IDE, this is the [`always_where_filters`](/modeling/topics/parameters/always-where-filters) parameter. extension_model_id: type: string format: uuid description: The ID of the extension model has_frozen_join_via_map: type: boolean description: Whether the join via map is frozen relationships: type: array description: >- Relationships defined in the topic. The properties in each object will typically mirror the [IDE parameters](/modeling/relationships/parameters) used in a model's `relationships` file. items: type: object properties: left_view_name: type: string description: The left view in the relationship right_view_name: type: string description: The right view in the relationship join_type: type: string description: The type of join (e.g., ALWAYS_LEFT) 'on': type: object description: The join condition expression properties: type: type: string operator: type: string operands: type: array items: type: object distinct: type: boolean sql: type: string description: The SQL expression for the join id: type: string description: Unique identifier for the relationship type: type: string description: The relationship type (e.g., `ONE_TO_MANY`) ignored: type: boolean description: Whether the relationship is ignored bidirectional: type: boolean description: Whether the relationship is bidirectional original_on_sql: type: string description: The original SQL for the join condition yaml_path_prefix: type: string description: The YAML path prefix for the relationship ide_file_name: type: string description: The file name for the topic in the IDE views: type: array description: >- A list of views included in the topic. The properties in each object will mirror the [IDE parameters](/modeling/views/parameters) available for views. items: type: object properties: name: type: string description: The name of the view label: type: string description: The display label for the view table_name: type: string description: The underlying database table name schema: type: string description: The database schema schema_label: type: string description: The display label for the schema extension_model_id: type: string format: uuid ide_file_name: type: string description: The name of the IDE file for the view yaml_path: type: string description: The YAML file path for the view filter_only_fields: type: array items: type: string is_pseudo_display_view: type: boolean primary_key: type: array description: Primary key fields for the view items: type: object properties: type: type: string field_name: type: string dimensions: type: array description: >- A list of dimensions defined in the view. The properties in each object will mirror the [IDE parameters](/modeling/dimensions/parameters) for `dimensions.` items: type: object properties: field_name: type: string view_name: type: string data_type: type: string description: >- Data type (e.g., STRING, NUMBER, TIMESTAMP) format: type: string description: Display format (e.g., ID) label: type: string description: Display label for the dimension description: type: string description: Description of the dimension view_label: type: string extension_model_id: type: string format: uuid is_dimension: type: boolean fully_qualified_name: type: string time_frames: type: array description: Available time frames for date dimensions items: type: string date_type: type: string description: >- Date granularity (e.g., DATE, WEEK, MONTH, QUARTER, YEAR) drill_fields: type: array description: Fields available for drilling items: type: string parent_field: type: string description: Parent field name for grouped dimensions parent_label: type: string description: Parent field label group_label: type: string description: Group label for the dimension is_group_parent_field: type: boolean description: Whether this is a parent field in a group data_type_metadata: type: object description: Additional metadata about the data type properties: is_date_type: type: boolean ai_context: type: string description: Context hints for AI usage measures: type: array description: >- Measures defined in the view. The properties in each object will mirror the [IDE parameters](/modeling/measures/parameters) for `measures.` items: type: object properties: type: type: string description: Measure type (e.g., aggregation) field_name: type: string view_name: type: string aggregate_type: type: string description: Aggregation type (e.g., COUNT, SUM, AVG) data_type: type: string label: type: string format: type: string view_label: type: string ignored: type: boolean description: Whether the measure is ignored display_sql: type: string description: SQL displayed in the UI dialect_sql: type: string description: SQL specific to the database dialect fully_qualified_name: type: string filters: type: object description: Filters applied to the measure example: success: true topic: name: Customers base_view_name: main__customers label: Customers default_filters: {} join_via_map: main__orders: [] main__order_items: - main__orders join_via_map_key_order: - main__orders - main__order_items ignored_props: [] always_where_filters: {} extension_model_id: 5da4e30e-45e2-4693-b87d-51c39d69963f has_frozen_join_via_map: true relationships: - left_view_name: main__orders right_view_name: main__customers join_type: ALWAYS_LEFT sql: ${main__orders.customer_id} = ${main__customers.id} id: main__orders_main__customers type: ASSUMED_MANY_TO_ONE ignored: false bidirectional: false ide_file_name: Customers.topic views: - name: main__customers label: Customers table_name: customers schema: main schema_label: Main extension_model_id: 5da4e30e-45e2-4693-b87d-51c39d69963f ide_file_name: main/customers.view yaml_path: main__customers.view filter_only_fields: [] is_pseudo_display_view: false primary_key: - type: field field_name: main__customers.id dimensions: - field_name: country view_name: main__customers data_type: STRING description: User's country view_label: Customers is_dimension: true fully_qualified_name: main__customers.country - field_name: created_date view_name: main__customers data_type: TIMESTAMP time_frames: - null - DATE - WEEK - MONTH - QUARTER - YEAR date_type: DATE description: Date of user creation parent_field: created_date parent_label: Created Date view_label: Customers group_label: Created Date is_dimension: true is_group_parent_field: true fully_qualified_name: main__customers.created_date measures: - type: aggregation field_name: count view_name: main__customers aggregate_type: COUNT data_type: NUMBER ignored: false label: Customers Count format: NUMBER_0 view_label: Customers display_sql: COUNT(*) dialect_sql: COUNT(*) fully_qualified_name: main__customers.count '400': description: | Bad Request. Possible causes: - Invalid model UUID content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: Model with id does not exist status: 400 '404': description: | Not Found. Possible causes: - Model not found - Topic not found or access not permitted content: application/json: schema: $ref: '#/components/schemas/Error' examples: modelNotFound: summary: Model not found value: detail: Model with id does not exist status: 404 topicNotFound: summary: Topic not found value: detail: No such topic "" or access not permitted status: 404 '429': $ref: '#/components/responses/TooManyRequests' security: - bearerAuth: [] components: schemas: Error: type: object properties: error: type: string description: HTTP response code for the error example: message: type: string description: Detailed error description example: responses: TooManyRequests: description: Too Many Requests - Rate limit exceeded (60 requests/minute) content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Can be either an [Organization API Key](/api/authentication#organization-api-keys) or [Personal Access Token (PAT)](/api/authentication#personal-access-tokens-pat). Include in the `Authorization` header as: `Bearer YOUR_TOKEN` orgApiKey: type: http scheme: bearer bearerFormat: JWT description: > Requires an [Organization API Key](/api/authentication#organization-api-keys). Personal Access Tokens (PATs) are not supported for this endpoint. Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY` ````