# TikTok tools

Eight tools including followers and sampled audience countries implemented; live verification pending.

## Get a TikTok account

Tool: `tiktok_get_profile`

Public profile and published account statistics.

Endpoint: `POST /api/social/tools/tiktok_get_profile`

Cost: 5 product credits per call/page. No fixed number of rows per page. Use dry_run for the selected options' quote.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "handle": {
      "type": "string",
      "minLength": 1,
      "maxLength": 65,
      "pattern": "^@?[A-Za-z0-9._]+$"
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "max_credits": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "handle"
  ],
  "additionalProperties": false
}
```

## Get TikTok followers

Tool: `tiktok_get_followers`

One page of accessible followers and their published profile statistics.

Endpoint: `POST /api/social/tools/tiktok_get_followers`

Cost: 5 product credits per call/page. No fixed number of rows per page. Use dry_run for the selected options' quote.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "handle": {
      "type": "string",
      "minLength": 1,
      "maxLength": 65,
      "pattern": "^@?[A-Za-z0-9._]+$"
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 16384
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "max_credits": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "handle"
  ],
  "additionalProperties": false
}
```

## Get TikTok audience countries

Tool: `tiktok_get_audience`

Sampled audience-country percentages. Costs 26 supplier credits per call.

Endpoint: `POST /api/social/tools/tiktok_get_audience`

Cost: 130 product credits per call (26 supplier credits). Counts describe a sample, not total followers. Use dry_run for a quote.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "handle": {
      "type": "string",
      "minLength": 1,
      "maxLength": 65,
      "pattern": "^@?[A-Za-z0-9._]+$"
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "max_credits": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "handle"
  ],
  "additionalProperties": false
}
```

## Get TikTok videos

Tool: `tiktok_get_videos`

One page of account videos, latest or popular. Feed coverage is not exhaustive.

Endpoint: `POST /api/social/tools/tiktok_get_videos`

Cost: 5 product credits per call/page. No fixed number of rows per page. Use dry_run for the selected options' quote.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "handle": {
      "type": "string",
      "minLength": 1,
      "maxLength": 65,
      "pattern": "^@?[A-Za-z0-9._]+$"
    },
    "sort": {
      "default": "latest",
      "type": "string",
      "enum": [
        "latest",
        "popular"
      ]
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 16384
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "max_credits": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "handle"
  ],
  "additionalProperties": false
}
```

## Get a TikTok video

Tool: `tiktok_get_video`

One public video or slideshow by URL. Media downloading is disabled.

Endpoint: `POST /api/social/tools/tiktok_get_video`

Cost: 5 product credits per call/page. No fixed number of rows per page. Use dry_run for the selected options' quote.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "maxLength": 2048,
      "format": "uri"
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "max_credits": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
```

## Get TikTok comments

Tool: `tiktok_get_comments`

One page of comments. Empty pages do not prove that no comments exist.

Endpoint: `POST /api/social/tools/tiktok_get_comments`

Cost: 5 product credits per call/page. No fixed number of rows per page. Use dry_run for the selected options' quote.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "maxLength": 2048,
      "format": "uri"
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 16384
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "max_credits": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
```

## Search TikTok videos

Tool: `tiktok_search_videos`

One page of keyword results; popular maps to most-liked, year uses local date filtering.

Endpoint: `POST /api/social/tools/tiktok_search_videos`

Cost: 5 product credits per call/page. No fixed number of rows per page. Use dry_run for the selected options' quote.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "since": {
      "default": "month",
      "type": "string",
      "enum": [
        "day",
        "week",
        "month",
        "year",
        "all"
      ]
    },
    "sort": {
      "default": "relevance",
      "type": "string",
      "enum": [
        "relevance",
        "latest",
        "popular"
      ]
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 16384
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "max_credits": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
```

## Get a TikTok transcript

Tool: `tiktok_get_transcript`

Native captions, with optional AI fallback for videos up to two minutes. Long paid transcription is disabled.

Endpoint: `POST /api/social/tools/tiktok_get_transcript`

Cost: 5 product credits per call/page. No fixed number of rows per page. Use dry_run for the selected options' quote.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "maxLength": 2048,
      "format": "uri"
    },
    "language": {
      "type": "string",
      "pattern": "^[a-zA-Z]{2}$"
    },
    "ai_fallback": {
      "default": false,
      "type": "boolean"
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "max_credits": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
```