tencent cloud

APIs

DocumentationAPIsCloud Log ServiceTopic Management APIsCreateTopic

CreateTopic

Download
Focus Mode
Font Size
Last updated: 2026-06-10 15:00:22

1. API Description

Domain name for API request: cls.intl.tencentcloudapi.com.

This API is used to create logs or metric topics.

A maximum of 100 requests can be initiated per second for this API.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common Params. The value used for this API: CreateTopic.
Version Yes String Common Params. The value used for this API: 2020-10-16.
Region Yes String Common Params. For more information, please see the list of regions supported by the product.
LogsetId Yes String

Logset ID
TopicName Yes String

Topic name
Name limitation

  • Cannot be an empty string
  • Cannot contain character '
PartitionCount No Integer

Topic partition count. Default creation is 1 partition. Supports a maximum of 10 partitions.
Tags.N No Array of Tag

Tag description list, by specifying this parameter, you can simultaneously bind a tag to the corresponding topic. Up to 10 tag key-value pairs are supported, and the same resource can only be bound to the same tag key.
AutoSplit No Boolean

Whether to enable auto-split, true by default
MaxSplitPartitions No Integer

When auto-split is enabled, the maximum number of partitions allowed for each topic is 50 by default.
StorageType No String

Log topic storage type. Available values: hot (standard storage), cold (infrequent storage). Default hot. This configuration is not supported for metric topics.
Period No Integer

Storage time, in days.

  • Log topic: When logs are collected to standard storage, the supported range is 1 to 3600 days. A value of 3640 indicates permanent retention.
  • Log topic: When logs are collected to infrequently accessed storage, the supported range is 7 to 3600 days. A value of 3640 indicates permanent retention.
  • Metric topic: The supported range is 1 to 3600 days. A value of 3640 indicates permanent retention.
Describes No String

Topic description
HotPeriod No Integer

0: Log topic disables log settlement.
Non-0: Number of days for standard storage after log settlement is enabled in the log topic. HotPeriod needs to be greater than or equal to 7 and less than Period.
Effective only when StorageType is hot. This configuration is not supported for metric topics.
Encryption No Integer

Encryption-related parameters. Encrypted regions and allowlisted users can pass this parameter, which cannot be passed in other scenarios.
0 or not passed: no encryption
1: kms-cls cloud service key encryption

Supported regions: ap-beijing, ap-guangzhou, ap-shanghai, ap-singapore, ap-bangkok, ap-jakarta, eu-frankfurt, ap-seoul, ap-tokyo
BizType No Integer

Topic type

  • 0: Log topic, default value
  • 1: Metric topic
TopicId No String

Custom topic ID, format: custom part-User APPID. If this parameter is left empty, ID will be automatically generated.

  • The custom part only supports lowercase letters, digits, and -, cannot start or end with -, and must be 3 to 40 characters in length.
  • The trailing part requires the use of - to concatenate User APPID. APPID can be queried on the page https://console.tencentcloud.com/developer.
  • If this field is specified, ensure uniqueness across all regions.
IsWebTracking No Boolean

Free authentication switch. False: turned off; true: turned on. Default false.
When enabled, anonymous access to the log topic will be supported for designated operations. For details, see log topic. This configuration is not supported for metric topics.
Extends No TopicExtendInfo

Topic extended information
IsSourceFrom No Boolean

Enable logging of public network source IP and server receipt time
BillingMode No Integer

Billing mode

Enumeration value:

  • 0: Function billing by usage
  • 1: Raw log size billing (currently only supported for some customers)

Default value: 0

3. Output Parameters

Parameter Name Type Description
TopicId String

Topic ID
RequestId String The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

4. Example

Example1 Creating a Metric Topic

create metric topic

Input Example

POST / HTTP/1.1
Host: cls.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateTopic
<Common request parameters>

{
    "LogsetId": "29ccb4c0-ab2f-47ab-9dcd-31413b057812",
    "TopicName": "testname",
    "BizType": 1,
    "Period": 12
}

Output Example

{
    "Response": {
        "TopicId": "6d069a26-1606-4142-9fa6-17ccee4f9bc9",
        "RequestId": "c1731e60-e00d-45ee-a9e8-5343d4f38325"
    }
}

Example2 Create Log Topic

Create a log topic

Input Example

POST / HTTP/1.1
Host: cls.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateTopic
<Common request parameters>

{
    "LogsetId": "29ccb4c0-ab2f-47ab-9dcd-31413b057812",
    "TopicName": "testname",
    "Period": 12
}

Output Example

{
    "Response": {
        "TopicId": "866f8a15-ae8e-4ab4-afb2-4ff169fa3dc0",
        "RequestId": "6ef60bec-0242-43af-bb20-270359fb54a7"
    }
}

5. Developer Resources

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code Description
FailedOperation Operation failed.
FailedOperation.InvalidPeriod The offline storage period cannot be less than 7 days.
FailedOperation.TopicCreating The topic is being created.
InternalError Internal error.
InvalidParameter Incorrect parameter.
InvalidParameter.TopicConflict There is already a log topic with the same name in the specified logset.
LimitExceeded The quota limit has been reached.
LimitExceeded.BillingTopicOutOfLimit A uin can only create one billing topic
LimitExceeded.Logset The number of logsets exceeds the limit.
LimitExceeded.Topic The number of log topics exceeds the limit.
MissingParameter Missing parameter.
OperationDenied Operation denied.
OperationDenied.AccountDestroy The account has been terminated.
OperationDenied.AccountIsolate The account has overdue payments.
OperationDenied.AccountNotExists The account does not exist.
ResourceNotFound.LogsetNotExist The specified logset does not exist.
Previous Topic: ResponsesNext Topic: ModifyTopic

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback