TikTok Marketing API Audience API
The Audience API from TikTok Marketing API — 18 operation(s) for audience.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/tiktok-ads-audience-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: TikTok API for Business — Marketing Audience API
description: TikTok API for Business (Marketing API) v1.3. This document is a mechanical union of the 202 per-operation OpenAPI 3.0.1 documents TikTok publishes in yml_files/ of its own SDK repository (https://github.com/tiktok/tiktok-business-api-sdk), which are the swagger-codegen inputs for TikTok's first-party Java/Python/JavaScript SDKs. Operation content (paths, parameters, responses, tags and the x-open-* extensions) is preserved verbatim; only info, servers and components.securitySchemes were written by API Evangelist, because the per-operation fragments carry placeholder info blocks and no servers block. The servers values are the production and sandbox base URLs TikTok documents at https://business-api.tiktok.com/portal/docs?id=1738855331457026 .
version: v1.3
contact:
name: TikTok API for Business support
url: https://business-api.tiktok.com/portal/docs?id=1795190020378625
termsOfService: https://business-api.tiktok.com/portal/docs?id=1737191804348417
x-source: https://github.com/tiktok/tiktok-business-api-sdk/tree/main/yml_files
x-harvested-by: API Evangelist enrichment pipeline
x-harvested: '2026-08-13'
servers:
- url: https://business-api.tiktok.com/open_api/v1.3
description: Production
- url: https://sandbox-ads.tiktok.com/open_api/v1.3
description: Sandbox
security:
- AccessToken: []
tags:
- name: Audience
paths:
/audience/insight/overlap/:
get:
operationId: Audience Insight Overlap
parameters:
- description: ''
in: query
name: advertiser_id
required: true
schema:
type: string
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-convert:
- int64(%s)
x-open-source: $.http.query.advertiser_id
x-open-field-id: 1
- description: ''
in: query
name: benchmark_custom_audience_id
required: true
schema:
type: string
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-convert:
- int64(%s)
x-open-source: $.http.query.benchmark_custom_audience_id
x-open-field-id: 2
- description: ''
in: query
name: comparison_custom_audience_ids
required: false
schema:
items:
type: string
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-convert:
- int64(%s)
maxItems: 4
type: array
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-source: $.http.query.comparison_custom_audience_ids
x-open-field-id: 3
- description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162).
in: query
name: Access-Token
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties:
code:
description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request.
format: int64
type:
- integer
- 'null'
x-open-allow-strlist: false
x-open-field-id: 4
data:
description: Returned data. The response for the SDK can be checked in the document for the API given in the description.
properties: {}
type:
- object
- 'null'
x-open-allow-strlist: false
x-open-field-id: 1
x-open-source: $.rpc.output.data
message:
description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097).
type:
- string
- 'null'
x-open-allow-strlist: false
x-open-field-id: 3
request_id:
description: The log ID of a request, which uniquely identifies the request.
type:
- string
- 'null'
x-open-allow-strlist: false
x-open-field-id: 2
type: object
x-open-allow-strlist: false
description: OK
summary: Get details of audience overlap. [Audience Insight Overlap](https://business-api.tiktok.com/portal/docs?id=1797023590780930)
tags:
- Audience
x-open-allowlist: {}
x-open-denylist: {}
x-open-rules:
base_rule: null
extra_rule:
base_source: []
http_query_source: []
http_source:
- name: advertiser_id
required: true
source: $.http.query.advertiser_id
type: number
- name: benchmark_custom_audience_id
required: true
source: $.http.query.benchmark_custom_audience_id
type: number
- children:
- type: number
is_expand: true
name: comparison_custom_audience_ids
required: false
source: $.http.query.comparison_custom_audience_ids
sub_type: number
type: array
- children:
- name: core_user_id
required: false
source: $.http.query.context_info.core_user_id
type: number
is_expand: true
name: context_info
required: false
source: $.http.query.context_info
type: object
plugins:
after_response: []
before_request: []
request_query_rule: null
request_rule:
advertiser_id: $.http.query.advertiser_id
benchmark_custom_audience_id: $.http.query.benchmark_custom_audience_id
comparison_custom_audience_ids: $.http.query.comparison_custom_audience_ids
context_info: $.http.query.context_info
response_cookie: []
response_header: []
response_rule:
benchmark_audience: $.rpc.output.benchmark_audience
comparison_audiences: $.rpc.output.comparison_audiences
x-open-scene-labels: []
x-open-settings:
pop_resp_nullvalue: true
/dmp/custom_audience/apply/:
post:
operationId: Dmp Custom_audience Apply
parameters:
- description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162).
in: query
name: Access-Token
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
action_mode:
description: 'Specific operation to be performed on the audience. Enum values: Apply, Disconnect.'
type: string
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-enum:
enum_package_expired: false
enum_package_id: null
enum_package_name: null
enums:
- description: ''
is_valid: true
key: Apply
value: Apply
- description: ''
is_valid: true
key: Disconnect
value: Disconnect
key_format: string
strict: true
use_part: false
validate_only: false
value_format: string
x-open-field-id: 4
x-open-source: $.http.body.action_mode
adgroup_ids:
description: 'A list of ad group IDs. Note: adgroup_ids and custom_audience_id should be under the same advertiser account. Otherwise, an error will occur. Lookalike Audience cannot be used in Reach & Frequency ads. Otherwise, an error will occur. See below for more details. 1. If the custom_audience_id is a Lookalike Audience and the adgroup_ids are Reach & Frequency ad groups, an error will occur. 2. If the custom_audience_id is a Lookalike Audience with the REACH_FREQUENCY audience subtype, an error will occur.'
items:
type: string
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-convert:
- int64(%s)
type: array
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-field-id: 3
x-open-source: $.http.body.adgroup_ids
advertiser_id:
description: Advertiser ID.
type: string
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-convert:
- int64(%s)
x-open-field-id: 1
x-open-source: $.http.body.advertiser_id
custom_audience_id:
description: Custom audience ID. You can only pass one custom audience ID.
type: string
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-convert:
- int64(%s)
x-open-field-id: 2
x-open-source: $.http.body.custom_audience_id
usage_mode:
description: 'Whether to include this audience in or exclude it from your ad groups. Required when action_mode is Apply. Enum values: Include, Exclude.'
type: string
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-enum:
enum_package_expired: false
enum_package_id: null
enum_package_name: null
enums:
- description: ''
is_valid: true
key: Include
value: Include
- description: ''
is_valid: true
key: Exclude
value: Exclude
key_format: string
strict: true
use_part: false
validate_only: false
value_format: string
x-open-field-id: 5
x-open-source: $.http.body.usage_mode
required:
- advertiser_id
- custom_audience_id
- adgroup_ids
- action_mode
type: object
x-open-allow-strlist: false
x-open-allow-strnum: false
responses:
'200':
content:
application/json:
schema:
properties:
code:
description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request.
format: int64
type:
- integer
- 'null'
x-open-allow-strlist: false
x-open-field-id: 4
data:
description: Returned data. The response for the SDK can be checked in the document for the API given in the description.
properties: {}
type:
- object
- 'null'
x-open-allow-strlist: false
x-open-field-id: 1
x-open-source: $.rpc.output.data
message:
description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097).
type:
- string
- 'null'
x-open-allow-strlist: false
x-open-field-id: 3
request_id:
description: The log ID of a request, which uniquely identifies the request.
type:
- string
- 'null'
x-open-allow-strlist: false
x-open-field-id: 2
type: object
x-open-allow-strlist: false
description: OK
summary: Apply a shared custom audience [Dmp Custom_audience Apply](https://ads.tiktok.com/marketing_api/docs?id=1740245827044354)
tags:
- Audience
x-open-allowlist: {}
x-open-denylist: {}
x-open-rules:
base_rule: null
extra_rule:
base_source: []
http_query_source: []
http_source:
- name: advertiser_id
required: true
source: $.http.body.advertiser_id
type: number
- name: custom_audience_id
required: true
source: $.http.body.custom_audience_id
type: number
- children:
- type: number
is_expand: true
name: adgroup_ids
required: true
source: $.http.body.adgroup_ids
sub_type: number
type: array
- name: action_mode
required: true
source: $.http.body.action_mode
type: string
- name: usage_mode
required: false
source: $.http.body.usage_mode
type: string
- children:
- name: core_user_id
required: false
source: $.context.core_user_id
type: number
is_expand: true
name: context_info
required: false
type: object
plugins:
after_response: []
before_request: []
request_query_rule: null
request_rule:
action_mode: $.http.body.action_mode
adgroup_ids: $.http.body.adgroup_ids
advertiser_id: $.http.body.advertiser_id
context_info:
core_user_id: $.context.core_user_id
custom_audience_id: $.http.body.custom_audience_id
usage_mode: $.http.body.usage_mode
response_cookie: []
response_header: []
response_rule: null
x-open-scene-labels: []
x-open-settings:
pop_resp_nullvalue: false
/dmp/custom_audience/apply/log/:
get:
operationId: Dmp Custom_audience Apply Log
parameters:
- description: Advertiser ID.
in: query
name: advertiser_id
required: true
schema:
type: string
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-convert:
- int64(%s)
x-open-source: $.http.query.advertiser_id
x-open-field-id: 1
- content:
application/json:
schema:
items:
type: string
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-convert:
- int64(%s)
type: array
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-source: $.http.query.custom_audience_ids
description: A list of custom audience IDs. Note The advertiser must be the owner of the custom_audience_ids. Otherwise, an error will occur. You can use the is_creator field returned in /dmp/custom_audience/list/ and /dmp/custom_audience/get/ to check whether this advertiser is the owner of this audience.
in: query
name: custom_audience_ids
required: true
x-open-field-id: 2
- description: 'Current page number. Default value: 1.'
in: query
name: page
required: false
schema:
default: 1
format: int32
type: integer
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-convert:
- int64(%s)
x-open-source: $.http.query.page
x-open-field-id: 3
- description: 'Page size. Default value: 10.'
in: query
name: page_size
required: false
schema:
default: 10
format: int32
type: integer
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-convert:
- int64(%s)
x-open-source: $.http.query.page_size
x-open-field-id: 4
- description: The timezone of returned value. For enum values, see Appendix - Time Zone. If not specified, UTC will be used.
in: query
name: timezone
required: false
schema:
type: string
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-source: $.http.query.timezone
x-open-field-id: 5
- description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162).
in: query
name: Access-Token
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties:
code:
description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request.
format: int64
type:
- integer
- 'null'
x-open-allow-strlist: false
x-open-field-id: 4
data:
description: Returned data. The response for the SDK can be checked in the document for the API given in the description.
properties: {}
type:
- object
- 'null'
x-open-allow-strlist: false
x-open-field-id: 1
x-open-source: $.rpc.output.data
message:
description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097).
type:
- string
- 'null'
x-open-allow-strlist: false
x-open-field-id: 3
request_id:
description: The log ID of a request, which uniquely identifies the request.
type:
- string
- 'null'
x-open-allow-strlist: false
x-open-field-id: 2
type: object
x-open-allow-strlist: false
description: OK
summary: Get the latest application log of custom audiences [Dmp Custom_audience Apply Log](https://ads.tiktok.com/marketing_api/docs?id=1758615737388033)
tags:
- Audience
x-open-allowlist: {}
x-open-denylist: {}
x-open-rules:
base_rule: null
extra_rule:
base_source: []
http_query_source: []
http_source:
- name: advertiser_id
required: true
source: $.http.query.advertiser_id
type: number
- children:
- type: number
is_expand: true
name: custom_audience_ids
required: true
source: $.http.query.custom_audience_ids
sub_type: number
type: array
- name: page
required: false
source: $.http.query.page
type: number
- name: page_size
required: false
source: $.http.query.page_size
type: number
- name: timezone
required: false
source: $.http.query.timezone
type: string
- children:
- name: app_id
required: false
source: $.context.app_id
type: number
- name: core_user_id
required: false
source: $.context.core_user_id
type: number
- name: developer_id
required: false
source: $.context.developer_id
type: number
- name: x_forwarded_for
required: false
source: $.context.is_same_identity
type: string
- name: x_real_ip
required: false
source: $.context.source_ip
type: string
is_expand: true
name: context_info
required: false
type: object
plugins:
after_response: []
before_request: []
request_query_rule: null
request_rule:
advertiser_id: $.http.query.advertiser_id
context_info:
app_id: $.context.app_id
core_user_id: $.context.core_user_id
developer_id: $.context.developer_id
x_forwarded_for: $.context.is_same_identity
x_real_ip: $.context.source_ip
custom_audience_ids: $.http.query.custom_audience_ids
page: $.http.query.page
page_size: $.http.query.page_size
timezone: $.http.query.timezone
response_cookie: []
response_header: []
response_rule:
advertiser_id: $.rpc.output.advertiser_id
list[][]:
- action_timestamp: $.rpc.output.data[].action_timestamp
adgroup_id: $.rpc.output.data[].adgroup_id
adgroup_name: $.rpc.output.data[].adgroup_name
audience_id: $.rpc.output.data[].audience_id
editor: $.rpc.output.data[].editor
usage_mode: $.rpc.output.data[].usage_mode
page_info: $.rpc.output.page_info
x-open-scene-labels: []
x-open-settings:
pop_resp_nullvalue: false
/dmp/custom_audience/create/:
post:
operationId: Dmp Custom_audience Create
parameters:
- description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162).
in: query
name: Access-Token
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
advertiser_id:
description: Advertiser ID.
type: string
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-convert:
- int64(%s)
x-open-field-id: 1
x-open-source: $.http.body.advertiser_id
audience_enhancement:
default: 'False'
description: ''
type: boolean
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-field-id: 7
x-open-source: $.http.body.audience_enhancement
audience_sub_type:
default: NORMAL
description: 'Audience sub type, indicating the type of ads that the audience can be used. Enum values: NORMAL Normal audience. It can be used in non-R&F ads. REACH_FREQUENCY: Audience for Reach & Frequency. It can only be used in R&F ads. Default: NORMAL.'
type: string
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-enum:
enum_package_expired: false
enum_package_id: 1804315821131778
enum_package_name: AudienceSubType
enums:
- description: ''
is_valid: true
key: NORMAL
value: '0'
- description: ''
is_valid: true
key: REACH_FREQUENCY
value: '1'
key_format: string
strict: true
use_part: false
validate_only: false
value_format: int32
x-open-field-id: 5
x-open-source: $.http.body.audience_sub_type
calculate_type:
description: Encryption type. calculate_type should be the same as all the files in the file_path, or you will not get a audience id or get an invalid audience id. For enum values, see Enumeration - Encryption Type.
type: string
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-enum:
enum_package_expired: false
enum_package_id: 1804315795490817
enum_package_name: CalculateType
enums:
- description: ''
is_valid: true
key: EMAIL_SHA256
value: '8'
- description: ''
is_valid: true
key: FIRST_MD5
value: '7'
- description: ''
is_valid: true
key: FIRST_SHA256
value: '6'
- description: ''
is_valid: true
key: GAID_MD5
value: '13'
- description: ''
is_valid: true
key: GAID_SHA256
value: '16'
- description: ''
is_valid: true
key: IDFA_MD5
value: '12'
- description: ''
is_valid: true
key: IDFA_SHA256
value: '15'
- description: ''
is_valid: true
key: MULTIPLE_TYPES
value: '100'
- description: ''
is_valid: true
key: PHONE_SHA256
value: '9'
key_format: string
strict: true
use_part: false
validate_only: false
value_format: int32
x-open-field-id: 3
x-open-source: $.http.body.calculate_type
custom_audience_name:
description: Audience name. Maximum of 128 characters.
maxLength: 128
minLength: 1
type: string
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-field-id: 2
x-open-source: $.http.body.custom_audience_name
file_paths:
description: List of file paths. The recommended size is <50 to ensure a stable request. You can use /dmp/custom_audience/update/ to append more data files to the audience. You get the file_path in response after you upload your file calling Upload audience files endpoint.
items:
default: ''
maxLength: 16
minLength: 16
type: string
x-open-allow-strlist: false
x-open-allow-strnum: false
maxItems: 500
minItems: 1
type: array
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-field-id: 4
x-open-source: $.http.body.file_paths
retention_in_days:
description: 'Number of days to retain the audience. Value range: [1, 365]. Note: If this field is passed, the expiration date will be the specified number of retention days from the date when the audience was created. Any operations to the audience CANNOT reset the expiration date. If this field is not passed, the expiration date will be 365 days from the last time the audience was applied to an active ad group or modified. Applying the audience to an active ad group or modifying the audience will reset the expiration date. To learn about the actions that will reset the expiration date, refer to the Help Center article Audience Expiration Policy.'
format: int32
maximum: 365
minimum: 1
type: integer
x-open-allow-strlist: false
x-open-allow-strnum: false
x-open-convert:
- int64(%s)
x-open-field-id: 6
x-open-source: $.http.body.retention_in_days
required:
- advertiser_id
- custom_audience_name
- calculate_type
- file_paths
type: object
x-open-allow-strlist: false
x-open-allow-strnum: false
responses:
'200':
content:
application/json:
schema:
properties:
code:
description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request.
format: int64
type:
- integer
- 'null'
x-open-allow-strlist: false
x-open-field-id: 4
data:
description: Returned data. The response for the SDK can be checked in the document for the API given in the description.
properties: {}
type:
- object
- 'null'
x-open-allow-strlist: false
x-open-field-id: 1
x-open-source: $.rpc.output.data
message:
description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097).
type:
- string
- 'null'
x-open-allow-strlist: false
x-open-field-id: 3
request_id:
description: The log ID of a request, which uniquely identifies the request.
type:
- string
- 'null'
x-open-allow-strlist: false
x-open-field-id: 2
type: object
x-open-allow-strlist: false
description: OK
summary: Create an audience by file [Dmp Custom_audience Create](https://ads.tiktok.com/marketing_api/docs?id=1739940570793985)
tags:
- Audience
x-open-allowlist: {}
x-open-denylist: {}
x-open-rules:
base_rule: null
extra_rule:
base_source: []
http_query_source: []
http_source:
- name: advertiser_id
required: true
source: $.http.body.advertiser_id
type: number
- name: custom_audience_name
required: true
source: $.http.body.custom_audience_name
type: string
- name: calculate_type
required: true
source: $.http.body.calculate_type
type: number
- children:
- type: string
is_expand: true
nam
# --- truncated at 32 KB (207 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tiktok-ads/refs/heads/main/openapi/tiktok-ads-audience-api-openapi.yml