{"openapi":"3.1.0","info":{"title":"doapisright","version":"1.0.0","description":"TikTok creator data APIs at doapisright.com. Authenticate with a Bearer API Key issued to your account. Each successful call costs 1 Credit. Success means HTTP 200 with code SUCCESS, including valid empty results. Failed calls and timeouts are not charged."},"servers":[{"url":"https://doapisright.com"}],"tags":[{"name":"TikTok","description":"TikTok creator data."}],"security":[{"apiKeyAuth":[]}],"paths":{"/api/v1/tiktok/creators":{"get":{"operationId":"tiktok-creator-by-username","x-api-id":"tiktok-creator-by-username","x-display-name":"Creator profile","tags":["TikTok"],"summary":"Look up a TikTok creator profile by username.","description":"Retrieve an indexed TikTok creator profile and audience metrics. Optional profile and metric fields are omitted when unavailable in the source data.\n\nEach successful call costs 1 Credit. Success means HTTP 200 with code SUCCESS, including valid empty results. Failed calls and timeouts are not charged.","x-credit-price":1,"x-billing-note":"A successful call is charged the displayed price even when the result is empty. Errors and timeouts leave no final charge.","security":[{"apiKeyAuth":[]}],"parameters":[{"name":"username","in":"query","required":true,"description":"TikTok username of the creator to look up. Surrounding whitespace is trimmed and one optional leading @ is removed. After normalization use 1–128 ASCII letters, digits, periods, or underscores. A profile URL is invalid.","schema":{"type":"string","title":"Username","pattern":"^[A-Za-z0-9._]{1,128}$","minLength":1,"maxLength":128},"example":"charlie","x-normalization":{"trim":true,"removePrefix":"@"}}],"responses":{"200":{"description":"Successful creator lookup.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorResponse"},"examples":{"success":{"summary":"Successful result","value":{"code":"SUCCESS","data":{"lookupStatus":"found","profile":{"platform":"tiktok","handle":"charlie","displayName":"Charlie Creates","bio":"Short videos about building small tools.","verified":true,"profileUrl":"https://www.tiktok.com/@charlie","platformUserId":"6987654321098765432","language":"en","accountCreatedAt":"2019-04-01T00:00:00.000Z","accountCreatedAtUnix":1554076800,"bioLink":{"url":"https://charliecreates.example"}},"metrics":{"followers":128400,"following":312,"likes":2410000,"friends":187}},"meta":{"request_id":"req_example_creator_01","version":"v1"}}},"empty":{"summary":"Indexed creator with no optional profile fields","value":{"code":"SUCCESS","data":{"lookupStatus":"found","profile":{"platform":"tiktok"},"metrics":{}},"meta":{"request_id":"req_example_creator_01","version":"v1"}}}}}}},"400":{"description":"The username is missing, repeated, or invalid after normalization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"BAD_REQUEST","message":"The username is missing, repeated, or invalid after normalization.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"401":{"description":"The Bearer API Key is missing, malformed, or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"UNAUTHORIZED","message":"The Bearer API Key is missing, malformed, or invalid.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"403":{"description":"The caller is not authorized to call this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"FORBIDDEN","message":"The caller is not authorized to call this API.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"404":{"description":"No indexed creator matches this username.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"NOT_FOUND","message":"No indexed creator matches this username.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"500":{"description":"An unexpected server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected server error occurred.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"502":{"description":"The upstream failed or returned an invalid or incomplete response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"UPSTREAM_FAILURE","message":"The upstream failed or returned an invalid or incomplete response.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"504":{"description":"The upstream exceeded the configured time limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"UPSTREAM_TIMEOUT","message":"The upstream exceeded the configured time limit.","meta":{"request_id":"req_example_error","version":"v1"}}}}}}}},"/api/v1/tiktok/audience":{"get":{"operationId":"tiktok-audience-by-username","x-api-id":"tiktok-audience-by-username","x-display-name":"Audience information","tags":["TikTok"],"summary":"Look up a TikTok creator's audience demographics by username.","description":"Retrieve the audience composition of an indexed TikTok creator: the top audience segment and the distribution of follower age, gender, region, and device brand. A dimension without available data contributes an empty top-audience object and an empty distribution.\n\nEach successful call costs 1 Credit. Success means HTTP 200 with code SUCCESS, including valid empty results. Failed calls and timeouts are not charged.","x-credit-price":1,"x-billing-note":"A successful call is charged the displayed price even when the result is empty. Errors and timeouts leave no final charge.","security":[{"apiKeyAuth":[]}],"parameters":[{"name":"username","in":"query","required":true,"description":"TikTok username of the creator to look up. Surrounding whitespace is trimmed and one optional leading @ is removed. After normalization use 1–128 ASCII letters, digits, periods, or underscores. A profile URL is invalid.","schema":{"type":"string","title":"Username","pattern":"^[A-Za-z0-9._]{1,128}$","minLength":1,"maxLength":128},"example":"charlie","x-normalization":{"trim":true,"removePrefix":"@"}}],"responses":{"200":{"description":"Successful audience lookup.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudienceResponse"},"examples":{"success":{"summary":"Successful result","value":{"code":"SUCCESS","data":{"profile":{"platform":"tiktok","handle":"charlie","profileUrl":"https://www.tiktok.com/@charlie"},"audienceAnalysis":{"topAudience":{"age":{"ageInterval":"18-24","ratio":0.312},"gender":{"gender":"female","ratio":0.5842},"region":{"country":"US","ratio":0.2271},"device":{"deviceBrand":"iPhone","ratio":0.41}},"audienceDistribution":{"ageDistribution":[{"ageInterval":"13-17","ratio":0.0918},{"ageInterval":"18-24","ratio":0.312},{"ageInterval":"25-34","ratio":0.2764}],"genderDistribution":[{"gender":"female","ratio":0.5842},{"gender":"male","ratio":0.4031}],"regionDistribution":[{"country":"US","ratio":0.2271},{"country":"GB","ratio":0.113}],"deviceDistribution":[{"deviceBrand":"iPhone","ratio":0.41},{"deviceBrand":"Android","ratio":0.5788}]}}},"meta":{"request_id":"req_example_audience_01","version":"v1"}}},"empty":{"summary":"Successful empty result (charged at the same price)","value":{"code":"SUCCESS","data":{"profile":{"platform":"tiktok","handle":"charlie","profileUrl":"https://www.tiktok.com/@charlie"},"audienceAnalysis":{"topAudience":{"age":{},"gender":{},"region":{},"device":{}},"audienceDistribution":{"ageDistribution":[],"genderDistribution":[],"regionDistribution":[],"deviceDistribution":[]}}},"meta":{"request_id":"req_example_audience_01","version":"v1"}}}}}}},"400":{"description":"The username is missing, repeated, or invalid after normalization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"BAD_REQUEST","message":"The username is missing, repeated, or invalid after normalization.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"401":{"description":"The Bearer API Key is missing, malformed, or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"UNAUTHORIZED","message":"The Bearer API Key is missing, malformed, or invalid.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"403":{"description":"The caller is not authorized to call this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"FORBIDDEN","message":"The caller is not authorized to call this API.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"404":{"description":"No indexed creator matches this username.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"NOT_FOUND","message":"No indexed creator matches this username.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"500":{"description":"An unexpected server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected server error occurred.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"502":{"description":"The upstream failed or returned an invalid or incomplete response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"UPSTREAM_FAILURE","message":"The upstream failed or returned an invalid or incomplete response.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"504":{"description":"The upstream exceeded the configured time limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"UPSTREAM_TIMEOUT","message":"The upstream exceeded the configured time limit.","meta":{"request_id":"req_example_error","version":"v1"}}}}}}}},"/api/v1/tiktok/labels":{"get":{"operationId":"tiktok-labels-by-username","x-api-id":"tiktok-labels-by-username","x-display-name":"Creator labels","tags":["TikTok"],"summary":"Look up a TikTok creator's content labels by username.","description":"Retrieve the English content labels classified for an indexed TikTok creator. The labels array is empty when the creator has no classified content labels.\n\nEach successful call costs 1 Credit. Success means HTTP 200 with code SUCCESS, including valid empty results. Failed calls and timeouts are not charged.","x-credit-price":1,"x-billing-note":"A successful call is charged the displayed price even when the result is empty. Errors and timeouts leave no final charge.","security":[{"apiKeyAuth":[]}],"parameters":[{"name":"username","in":"query","required":true,"description":"TikTok username of the creator to look up. Surrounding whitespace is trimmed and one optional leading @ is removed. After normalization use 1–128 ASCII letters, digits, periods, or underscores. A profile URL is invalid.","schema":{"type":"string","title":"Username","pattern":"^[A-Za-z0-9._]{1,128}$","minLength":1,"maxLength":128},"example":"charlie","x-normalization":{"trim":true,"removePrefix":"@"}}],"responses":{"200":{"description":"Successful creator labels lookup.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelsResponse"},"examples":{"success":{"summary":"Successful result","value":{"code":"SUCCESS","data":{"profile":{"platform":"tiktok","handle":"charlie","profileUrl":"https://www.tiktok.com/@charlie"},"labels":["Beauty & Personal Care","Travel","Fitness"]},"meta":{"request_id":"req_example_labels_01","version":"v1"}}},"empty":{"summary":"Successful empty result (charged at the same price)","value":{"code":"SUCCESS","data":{"profile":{"platform":"tiktok","handle":"charlie","profileUrl":"https://www.tiktok.com/@charlie"},"labels":[]},"meta":{"request_id":"req_example_labels_01","version":"v1"}}}}}}},"400":{"description":"The username is missing, repeated, or invalid after normalization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"BAD_REQUEST","message":"The username is missing, repeated, or invalid after normalization.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"401":{"description":"The Bearer API Key is missing, malformed, or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"UNAUTHORIZED","message":"The Bearer API Key is missing, malformed, or invalid.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"403":{"description":"The caller is not authorized to call this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"FORBIDDEN","message":"The caller is not authorized to call this API.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"404":{"description":"No indexed creator matches this username.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"NOT_FOUND","message":"No indexed creator matches this username.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"500":{"description":"An unexpected server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected server error occurred.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"502":{"description":"The upstream failed or returned an invalid or incomplete response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"UPSTREAM_FAILURE","message":"The upstream failed or returned an invalid or incomplete response.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"504":{"description":"The upstream exceeded the configured time limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"UPSTREAM_TIMEOUT","message":"The upstream exceeded the configured time limit.","meta":{"request_id":"req_example_error","version":"v1"}}}}}}}},"/api/v1/tiktok/region":{"get":{"operationId":"tiktok-region-by-username","x-api-id":"tiktok-region-by-username","x-display-name":"Region information","tags":["TikTok"],"summary":"Look up a TikTok creator's region by username.","description":"Retrieve the canonical region of an indexed TikTok creator: an ISO 3166-1 alpha-2 style code when known, together with its English region name. Both fields are null when the creator's region is unknown.\n\nEach successful call costs 1 Credit. Success means HTTP 200 with code SUCCESS, including valid empty results. Failed calls and timeouts are not charged.","x-credit-price":1,"x-billing-note":"A successful call is charged the displayed price even when the result is empty. Errors and timeouts leave no final charge.","security":[{"apiKeyAuth":[]}],"parameters":[{"name":"username","in":"query","required":true,"description":"TikTok username of the creator to look up. Surrounding whitespace is trimmed and one optional leading @ is removed. After normalization use 1–128 ASCII letters, digits, periods, or underscores. A profile URL is invalid.","schema":{"type":"string","title":"Username","pattern":"^[A-Za-z0-9._]{1,128}$","minLength":1,"maxLength":128},"example":"charlie","x-normalization":{"trim":true,"removePrefix":"@"}}],"responses":{"200":{"description":"Successful region lookup.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionResponse"},"examples":{"success":{"summary":"Successful result","value":{"code":"SUCCESS","data":{"profile":{"platform":"tiktok","handle":"charlie","profileUrl":"https://www.tiktok.com/@charlie"},"region":"US","regionName":"United States"},"meta":{"request_id":"req_example_region_01","version":"v1"}}},"empty":{"summary":"Successful empty result (charged at the same price)","value":{"code":"SUCCESS","data":{"profile":{"platform":"tiktok","handle":"charlie","profileUrl":"https://www.tiktok.com/@charlie"},"region":null,"regionName":null},"meta":{"request_id":"req_example_region_01","version":"v1"}}}}}}},"400":{"description":"The username is missing, repeated, or invalid after normalization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"BAD_REQUEST","message":"The username is missing, repeated, or invalid after normalization.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"401":{"description":"The Bearer API Key is missing, malformed, or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"UNAUTHORIZED","message":"The Bearer API Key is missing, malformed, or invalid.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"403":{"description":"The caller is not authorized to call this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"FORBIDDEN","message":"The caller is not authorized to call this API.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"404":{"description":"No indexed creator matches this username.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"NOT_FOUND","message":"No indexed creator matches this username.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"500":{"description":"An unexpected server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected server error occurred.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"502":{"description":"The upstream failed or returned an invalid or incomplete response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"UPSTREAM_FAILURE","message":"The upstream failed or returned an invalid or incomplete response.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"504":{"description":"The upstream exceeded the configured time limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"UPSTREAM_TIMEOUT","message":"The upstream exceeded the configured time limit.","meta":{"request_id":"req_example_error","version":"v1"}}}}}}}},"/api/v1/tiktok/partnership_recommendations":{"get":{"operationId":"tiktok-partnership-recommendations-by-username","x-api-id":"tiktok-partnership-recommendations-by-username","x-display-name":"Partnership recommendations","tags":["TikTok"],"summary":"Look up partnership recommendations for a TikTok creator by username.","description":"Retrieve the brand cooperation suggestions derived for an indexed TikTok creator. Recommendation items are open objects whose fields vary by creator, with text values provided in English. The list is empty when no recommendation exists.\n\nEach successful call costs 1 Credit. Success means HTTP 200 with code SUCCESS, including valid empty results. Failed calls and timeouts are not charged.","x-credit-price":1,"x-billing-note":"A successful call is charged the displayed price even when the result is empty. Errors and timeouts leave no final charge.","security":[{"apiKeyAuth":[]}],"parameters":[{"name":"username","in":"query","required":true,"description":"TikTok username of the creator to look up. Surrounding whitespace is trimmed and one optional leading @ is removed. After normalization use 1–128 ASCII letters, digits, periods, or underscores. A profile URL is invalid.","schema":{"type":"string","title":"Username","pattern":"^[A-Za-z0-9._]{1,128}$","minLength":1,"maxLength":128},"example":"charlie","x-normalization":{"trim":true,"removePrefix":"@"}}],"responses":{"200":{"description":"Successful partnership recommendations lookup.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnershipRecommendationsResponse"},"examples":{"success":{"summary":"Successful result","value":{"code":"SUCCESS","data":{"profile":{"platform":"tiktok","handle":"charlie","profileUrl":"https://www.tiktok.com/@charlie"},"list":[{"industry":"Beauty & Personal Care","recommendation_reason":"Audience engagement concentrates in beauty and skincare content."},{"industry":"Consumer Electronics","recommendation_reason":"The creator's device-brand audience share indicates strong electronics affinity."}]},"meta":{"request_id":"req_example_partnership_01","version":"v1"}}},"empty":{"summary":"Successful empty result (charged at the same price)","value":{"code":"SUCCESS","data":{"profile":{"platform":"tiktok","handle":"charlie","profileUrl":"https://www.tiktok.com/@charlie"},"list":[]},"meta":{"request_id":"req_example_partnership_01","version":"v1"}}}}}}},"400":{"description":"The username is missing, repeated, or invalid after normalization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"BAD_REQUEST","message":"The username is missing, repeated, or invalid after normalization.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"401":{"description":"The Bearer API Key is missing, malformed, or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"UNAUTHORIZED","message":"The Bearer API Key is missing, malformed, or invalid.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"403":{"description":"The caller is not authorized to call this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"FORBIDDEN","message":"The caller is not authorized to call this API.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"404":{"description":"No indexed creator matches this username.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"NOT_FOUND","message":"No indexed creator matches this username.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"500":{"description":"An unexpected server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected server error occurred.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"502":{"description":"The upstream failed or returned an invalid or incomplete response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"UPSTREAM_FAILURE","message":"The upstream failed or returned an invalid or incomplete response.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"504":{"description":"The upstream exceeded the configured time limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"UPSTREAM_TIMEOUT","message":"The upstream exceeded the configured time limit.","meta":{"request_id":"req_example_error","version":"v1"}}}}}}}},"/api/v1/tiktok/similar_account":{"get":{"operationId":"tiktok-similar-account-by-username","x-api-id":"tiktok-similar-account-by-username","x-display-name":"Similar accounts","tags":["TikTok"],"summary":"Look up accounts similar to a TikTok creator by username.","description":"Retrieve up to six indexed TikTok accounts that resemble the queried creator in audience size, region, labels, and audience composition. Optional account fields are omitted when unavailable, and the list is empty when no comparable account exists.\n\nEach successful call costs 1 Credit. Success means HTTP 200 with code SUCCESS, including valid empty results. Failed calls and timeouts are not charged.","x-credit-price":1,"x-billing-note":"A successful call is charged the displayed price even when the result is empty. Errors and timeouts leave no final charge.","security":[{"apiKeyAuth":[]}],"parameters":[{"name":"username","in":"query","required":true,"description":"TikTok username of the creator to look up. Surrounding whitespace is trimmed and one optional leading @ is removed. After normalization use 1–128 ASCII letters, digits, periods, or underscores. A profile URL is invalid.","schema":{"type":"string","title":"Username","pattern":"^[A-Za-z0-9._]{1,128}$","minLength":1,"maxLength":128},"example":"charlie","x-normalization":{"trim":true,"removePrefix":"@"}}],"responses":{"200":{"description":"Successful similar accounts lookup.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimilarAccountResponse"},"examples":{"success":{"summary":"Successful result","value":{"code":"SUCCESS","data":{"profile":{"platform":"tiktok","handle":"charlie","profileUrl":"https://www.tiktok.com/@charlie"},"list":[{"userName":"maya.creates","nickName":"Maya Creates","avatarUrl":"https://cdn.example.example/avatars/maya.creates.jpg","profileUrl":"https://www.tiktok.com/@maya.creates","followerCount":96500},{"userName":"sam.builds","followerCount":158000}]},"meta":{"request_id":"req_example_similar_01","version":"v1"}}},"empty":{"summary":"Successful empty result (charged at the same price)","value":{"code":"SUCCESS","data":{"profile":{"platform":"tiktok","handle":"charlie","profileUrl":"https://www.tiktok.com/@charlie"},"list":[]},"meta":{"request_id":"req_example_similar_01","version":"v1"}}}}}}},"400":{"description":"The username is missing, repeated, or invalid after normalization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"BAD_REQUEST","message":"The username is missing, repeated, or invalid after normalization.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"401":{"description":"The Bearer API Key is missing, malformed, or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"UNAUTHORIZED","message":"The Bearer API Key is missing, malformed, or invalid.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"403":{"description":"The caller is not authorized to call this API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"FORBIDDEN","message":"The caller is not authorized to call this API.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"404":{"description":"No indexed creator matches this username.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"NOT_FOUND","message":"No indexed creator matches this username.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"500":{"description":"An unexpected server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"INTERNAL_ERROR","message":"An unexpected server error occurred.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"502":{"description":"The upstream failed or returned an invalid or incomplete response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"UPSTREAM_FAILURE","message":"The upstream failed or returned an invalid or incomplete response.","meta":{"request_id":"req_example_error","version":"v1"}}}}},"504":{"description":"The upstream exceeded the configured time limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"example":{"code":"UPSTREAM_TIMEOUT","message":"The upstream exceeded the configured time limit.","meta":{"request_id":"req_example_error","version":"v1"}}}}}}}}},"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","description":"A doapisright API Key issued to your account. It is separate from server-to-server credentials."}},"schemas":{"ResponseMeta":{"type":"object","required":["request_id","version"],"properties":{"request_id":{"type":"string","description":"Request ID correlating this response."},"version":{"type":"string","const":"v1"}}},"CreatorResponse":{"type":"object","required":["code","data","meta"],"properties":{"code":{"type":"string","const":"SUCCESS"},"data":{"type":"object","required":["lookupStatus","profile","metrics"],"properties":{"lookupStatus":{"type":"string","const":"found"},"profile":{"type":"object","required":["platform"],"properties":{"platform":{"type":"string","const":"tiktok"},"handle":{"type":"string"},"displayName":{"type":"string"},"bio":{"type":"string"},"avatarUrl":{"type":"string"},"profileUrl":{"type":"string"},"platformUserId":{"type":"string"},"secUid":{"type":"string"},"language":{"type":"string"},"accountCreatedAt":{"type":"string"},"verified":{"type":"boolean"},"accountCreatedAtUnix":{"type":"integer","minimum":0},"bioLink":{"type":"object","required":["url"],"properties":{"url":{"type":"string"}}}}},"metrics":{"type":"object","properties":{"followers":{"type":"integer","minimum":0},"following":{"type":"integer","minimum":0},"likes":{"type":"integer","minimum":0},"friends":{"type":"integer","minimum":0}}}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"ErrorEnvelope":{"type":"object","required":["code","meta"],"properties":{"code":{"type":"string","enum":["BAD_REQUEST","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","INTERNAL_ERROR","UPSTREAM_FAILURE","UPSTREAM_TIMEOUT"]},"message":{"type":"string"},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"ProfileRef":{"type":"object","required":["platform"],"properties":{"platform":{"type":"string","const":"tiktok"},"handle":{"type":"string","description":"Canonical TikTok username of the queried creator."},"profileUrl":{"type":"string","description":"TikTok profile URL of the queried creator."}}},"AudienceResponse":{"type":"object","required":["code","data","meta"],"properties":{"code":{"type":"string","const":"SUCCESS"},"data":{"type":"object","required":["profile","audienceAnalysis"],"properties":{"profile":{"$ref":"#/components/schemas/ProfileRef"},"audienceAnalysis":{"type":"object","required":["topAudience","audienceDistribution"],"properties":{"topAudience":{"type":"object","description":"The single largest audience segment per dimension; an object without a segment value means that dimension has no top entry.","properties":{"age":{"$ref":"#/components/schemas/AudienceTopAge"},"gender":{"$ref":"#/components/schemas/AudienceTopGender"},"region":{"$ref":"#/components/schemas/AudienceTopRegion"},"device":{"$ref":"#/components/schemas/AudienceTopDevice"}}},"audienceDistribution":{"type":"object","required":["ageDistribution","genderDistribution","regionDistribution","deviceDistribution"],"properties":{"ageDistribution":{"type":"array","items":{"$ref":"#/components/schemas/AudienceAgeShare"}},"genderDistribution":{"type":"array","items":{"$ref":"#/components/schemas/AudienceGenderShare"}},"regionDistribution":{"type":"array","items":{"$ref":"#/components/schemas/AudienceRegionShare"}},"deviceDistribution":{"type":"array","items":{"$ref":"#/components/schemas/AudienceDeviceShare"}}}}}}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"AudienceTopAge":{"type":"object","properties":{"ageInterval":{"type":["string","null"]},"ratio":{"type":"number","minimum":0,"maximum":1}}},"AudienceTopGender":{"type":"object","properties":{"gender":{"type":["string","null"]},"ratio":{"type":"number","minimum":0,"maximum":1}}},"AudienceTopRegion":{"type":"object","properties":{"country":{"type":["string","null"]},"ratio":{"type":"number","minimum":0,"maximum":1}}},"AudienceTopDevice":{"type":"object","properties":{"deviceBrand":{"type":["string","null"]},"ratio":{"type":"number","minimum":0,"maximum":1}}},"AudienceAgeShare":{"type":"object","required":["ratio"],"properties":{"ageInterval":{"type":"string"},"ratio":{"type":"number","minimum":0,"maximum":1}}},"AudienceGenderShare":{"type":"object","required":["ratio"],"properties":{"gender":{"type":"string"},"ratio":{"type":"number","minimum":0,"maximum":1}}},"AudienceRegionShare":{"type":"object","required":["ratio"],"properties":{"country":{"type":"string"},"ratio":{"type":"number","minimum":0,"maximum":1}}},"AudienceDeviceShare":{"type":"object","required":["ratio"],"properties":{"deviceBrand":{"type":"string"},"ratio":{"type":"number","minimum":0,"maximum":1}}},"LabelsResponse":{"type":"object","required":["code","data","meta"],"properties":{"code":{"type":"string","const":"SUCCESS"},"data":{"type":"object","required":["profile","labels"],"properties":{"profile":{"$ref":"#/components/schemas/ProfileRef"},"labels":{"type":"array","items":{"type":"string"},"description":"English content labels of the creator; empty when none are classified."}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"RegionResponse":{"type":"object","required":["code","data","meta"],"properties":{"code":{"type":"string","const":"SUCCESS"},"data":{"type":"object","required":["profile","region","regionName"],"properties":{"profile":{"$ref":"#/components/schemas/ProfileRef"},"region":{"type":["string","null"],"description":"Canonical upper-case region code, or null when unknown."},"regionName":{"type":["string","null"],"description":"English region name, or null when the region cannot be resolved."}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"PartnershipRecommendationsResponse":{"type":"object","required":["code","data","meta"],"properties":{"code":{"type":"string","const":"SUCCESS"},"data":{"type":"object","required":["profile","list"],"properties":{"profile":{"$ref":"#/components/schemas/ProfileRef"},"list":{"type":"array","description":"Open recommendation items; fields vary by creator and text values are English.","items":{"type":"object","additionalProperties":true}}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"SimilarAccountResponse":{"type":"object","required":["code","data","meta"],"properties":{"code":{"type":"string","const":"SUCCESS"},"data":{"type":"object","required":["profile","list"],"properties":{"profile":{"$ref":"#/components/schemas/ProfileRef"},"list":{"type":"array","items":{"$ref":"#/components/schemas/SimilarAccount"}}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"SimilarAccount":{"type":"object","required":["userName","followerCount"],"properties":{"userName":{"type":"string"},"nickName":{"type":"string"},"avatarUrl":{"type":"string"},"profileUrl":{"type":"string"},"followerCount":{"type":"integer","minimum":0}}}}}}