> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# How do I organize TikTok links from teammates without querying the same video twice?

> Extract string aweme_id values from standard TikTok /video/ URLs and deduplicate locally before calling tiktok.app.v3.fetch_video_comments or resolving short links.

Deduplicate teammate TikTok links locally by string video ID before running any paid call. `tiktok.app.v3.fetch_video_comments` accepts only the numeric ID after `/video/` in a standard `/@account/video/video_id` URL as `aweme_id`, never a full URL or an unresolved short link. When two links share the same `aweme_id`, prepare one first-page request and retain both links as sources; `tiktok_ids.py` below generates `requests.json` and `audit.json` locally.

## Separate incoming links before resolution

| Input                                                         | Local preparation                                                                     | Next step                                                                     |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Standard `/@handle/video/video_id` URL                        | Preserve the source URL and extract the digits after `/video/` as a string `aweme_id` | Prepare one first-page comment request.                                       |
| Repeated ID or the same video with different query parameters | Merge entries by string `aweme_id` while retaining all input sources                  | Avoid duplicate first-page requests for the same video.                       |
| Unresolved `vt`/`vm` share link                               | Keep the short link unresolved rather than placing the short link in `aweme_id`       | Verify the final video page or approve a separate share-link resolution call. |
| Profile, photo URL, other domain, or numeric JSON ID          | Reject the entry instead of forcing arbitrary digits into `aweme_id`                  | Verify the source URL or re-export identifiers as strings.                    |

A video ID (`aweme_id`) is not a handle, a display name, an author identifier, or a parent comment ID. Video comment requests take `aweme_id`, while expanding a reply thread requires the real parent comment ID.

## Inspect the local plan before executing requests

`tiktok_ids.py` writes two local files:

* **`requests.json`:** A list of **unexecuted independent first-page requests**, not a batch API call.
* **`audit.json`:** A record of unique targets, duplicate inputs, and rejected inputs.

Check `audit.json` for unexpected targets, an empty plan, or unresolved short links before approving the paid request count. Generating `requests.json` and `audit.json` makes no paid calls and does not verify that a video exists. If every input is rejected, nothing was collected. Keep every identifier as a string because a numeric ID rounded by a spreadsheet or JSON number parser cannot be recovered by converting the rounded number back to text.

When you have a standard URL and need only comments, extract `aweme_id` directly from the URL. When you also need descriptions and metrics, reuse saved video detail or follow the [video-performance workflow](/guides/tiktok-share-metrics) rather than running two detail routes for the same video.

## Resolve a shared link into a usable aweme_id

Call `tiktok.app.v3.fetch_one_video_by_share_url_v2` with the full link in `share_url`. A successful response lists videos in `data.aweme_details`, where the target video's `aweme_id` is the input for comment requests. Do not confuse `aweme_id` with author fields: `author.unique_id` is a handle, `author.nickname` is a display name, and `author.sec_uid` identifies the author.

Resolving a share link via `tiktok.app.v3.fetch_one_video_by_share_url_v2` is a paid platform query, not local string parsing. With a standard `/video/` URL and a need for comments only, extract `aweme_id` locally and skip the detail call. Fetch video detail only when you need the caption, author metadata, and engagement metrics. Confirm `status=succeeded`; if `data.aweme_details` is empty or returns multiple candidates, stop and check the source link rather than taking the first entry silently.

[Share link to a metric snapshot](/guides/tiktok-share-metrics)

Sources: the input contract and observed output of `data:tiktok.app.v3.fetch_one_video_by_share_url_v2`.

## Prepare a deduplicated comment-request list locally

Suppose a teammate sends 20 standard TikTok video links containing duplicates and tracking query parameters. The goal is one first-page comment request per unique video rather than 20 redundant detail lookups. Save the links or raw string IDs as a JSON array in `links.json` without storing IDs as JSON numbers:

```json
["https://www.tiktok.com/@example/video/1234567890123456789?share=1", "1234567890123456789", "https://vt.tiktok.com/example/"]
```

The sample strings above illustrate accepted and rejected input shapes rather than live videos. Save the script below as `tiktok_ids.py` and run `python3 tiktok_ids.py links.json prepared-comments`. `tiktok_ids.py` accepts bare positive decimal string IDs and HTTPS `tiktok.com` or `www.tiktok.com` `/@handle/video/ID` paths; all other link forms are recorded for explicit resolution. Query strings and fragments never become IDs. `tiktok_ids.py` makes no network calls, preserves original inputs, and refuses to overwrite an existing output directory.

```python
import json, pathlib, re, sys
from urllib.parse import urlsplit
source, target = map(pathlib.Path, sys.argv[1:3])
inputs = json.loads(source.read_text(encoding='utf-8'))
if not isinstance(inputs,list) or not 1 <= len(inputs) <= 100:
    raise ValueError('Supply 1–100 strings; no network calls are made')
resolved, rejected, order = {}, [], []
for n,value in enumerate(inputs,1):
    if not isinstance(value,str):
        rejected.append({'input_index':n,'reason':'require_original_string'});continue
    text=value.strip();identifier=None
    if re.fullmatch(r'[1-9][0-9]*',text):
        identifier=text
    else:
        try:
            u=urlsplit(text)
            valid=u.scheme=='https' and u.hostname in ('tiktok.com','www.tiktok.com') and not u.username and not u.password and u.port in (None,443)
            match=re.fullmatch(r'/@[^/\s]+/video/([1-9][0-9]*)/?',u.path) if valid else None
            if match: identifier=match.group(1)
        except ValueError:
            pass
    if identifier is None:
        rejected.append({'input_index':n,'input':value,'reason':'needs_resolved_standard_video_url_or_string_id'});continue
    if identifier not in resolved:
        resolved[identifier]=[];order.append(identifier)
    resolved[identifier].append({'input_index':n,'input':value})
requests=[{'action':'tiktok.app.v3.fetch_video_comments','params':{'aweme_id':i,'cursor':0,'count':20}} for i in order]
target.mkdir(parents=True,exist_ok=False)
(target/'requests.json').write_text(json.dumps(requests,ensure_ascii=False,indent=2),encoding='utf-8')
(target/'audit.json').write_text(json.dumps({'unique_ids':len(order),'sources':resolved,'rejected':rejected,
    'requests_executed':False,'id_existence_verified':False,'example_first_page_cost_usd':format(len(order)*3/1000,'.3f')},ensure_ascii=False,indent=2),encoding='utf-8')
print(json.dumps({'unique_ids':len(order),'rejected_inputs':len(rejected),'requests_executed':False}))

```

Review `audit.json` before sending any request. `requests.json` holds separate first-page request bodies rather than a batch API payload; send each request body individually within your approved budget. At the checked reference rate of `$0.003` per comment-page call, 20 distinct first pages cost `$0.060`, and repeated links collapse locally. That estimate excludes extra pages, reply threads, share-link resolution, and model analysis; recheck current pricing before execution. An empty `requests` array paired with rejected inputs means no target was collected.

## Boundaries between comments and reply threads

`tiktok_ids.py` never extracts digits from `vm`/`vt` short links, profile URLs, photo URLs, or non-TikTok hosts. Resolve supported share links through `tiktok.app.v3.fetch_one_video_by_share_url_v2` or obtain the final `/video/` URL, then rerun `tiktok_ids.py` into a new output folder. Never substitute a query-string number, comment ID, `author.sec_uid`, or handle for `aweme_id`. Valid identifier syntax does not prove that a video exists, is public, or has comments; inspect the actual response status after execution.

Top-level comments (`tiktok.app.v3.fetch_video_comments`) take `aweme_id`, whereas reply threads (`tiktok.app.v3.fetch_video_comment_replies`) take `item_id` plus the thread's `comment_id`. Do not send `requests.json` unchanged to the replies action. This page covers identifier preparation only; check the comment and reply contracts separately before mapping output fields, and note that the current public reply example has no populated payload to assume fixed response fields from.

## Contracts and related questions

Before running a request, inspect the contracts for free: `data:tiktok.app.v3.fetch_video_comments`, `data:tiktok.app.v3.fetch_video_comment_replies`.

[Back to TikTok questions](/faq/tiktok).