Query semantic entries

Lists business definition entries in the knowledge base in pages.

HTTP

GET $CLOUDSIGMA_API_BASE/semantic-models/{model_id}/entries

Before you call this API

Configure the regional API endpoint and authentication, and select the target workspace.

First query the knowledge base list to obtain the knowledge base ID.

Set the operation-specific values used in the request:

• $MODEL_ID: ID of the knowledge base to be queried.

Request

Input examples

Shell

curl "$CLOUDSIGMA_API_BASE/semantic-models/$MODEL_ID/entries?kind=metric&page_size=20" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

Parameter reference

Path parameters

Parameters	Type	Description
model_id	integer	Knowledge base ID.

Query parameters

Parameter	Type	Required	Description
kind	string	No	Entry type filter criteria; available values and their configuration fields can be found in Create Semantic Entry.
page_size	integer	No	The number of items in a single page, ranging from 1 to 100; when not transmitted, it is 20.
page_token	string	No	next_page_token from the previous page response.

Successful response

Returns 200 on success. Save data.items[].id and use it for subsequent update and deletion interfaces.

Response example

JSON

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "items": [
      {
        "id": 501,
        "kind": "metric",
        "key": "total_rows",
        "tables": ["orders"],
        "spec": {
          "expr": "COUNT(*)"
        },
        "created_at": 1735632000,
        "updated_at": 1735632000
      }
    ],
    "total": 1,
    "next_page_token": ""
  }
}

Show full code

Field reference

The response fields are as follows.

Field	Type	Description
code	string	OK on success.
msg	string	OK on success.
data.items	object[]	The semantic entry of the current page.
data.items[].id	integer	Entry ID.
data.items[].kind	string	Entry type.
data.items[].key	string	Stable reference key within the knowledge base.
data.items[].tables	array[string]	Association table name; may be omitted if not set.
data.items[].spec	object	Type-specific configuration object corresponding to data.items[].kind; see Create semantic entry for fields.
data.items[].created_at	integer	Creation time as a Unix timestamp.
data.items[].updated_at	integer	Update time as a Unix timestamp.
data.total	integer	The total number of entries matching the filter criteria.
data.next_page_token	string	Next page token; if empty, there is no next page.

In field paths, [] means each item in an array. For example, data.items[].id is the id field of each item in data.items.

Read next page

When data.next_page_token in the response is not empty, it is passed to the next page request as page_token; when it is empty, it means that the last page has been read.

Error response

Response example

JSON

{
  "code": "ErrParamInvalid",
  "msg": "page_size is invalid",
  "data": null
}

Field reference

Common HTTP errors

HTTP status code	error code	Common causes	Recommended actions
400	ErrParamInvalid	model_id, kind or page_size are not valid.	Correct the parameters and try again.
401	ErrUnauthorized	The API Key is invalid or has expired.	Check API Key.
403	ErrForbidden	The caller does not have read permission.	Check workspace and object authorization.
404	ErrNotFound	The knowledge base does not exist or is not visible.	Reconfirm model_id.
500	ErrServer	The service failed to read the entry.	Keep the desensitized response information and try again.

Follow-up operations

When you need to add a new one, Create semantic entries; after selecting an existing entry, you can Update semantic entries or Delete semantic entries.

Last updated on Sep 15, 2026