What evidence should I give AI to review TikTok video performance?
Give AI a verified snapshot of each video’s description and engagement counters, not the share links alone. For each TikTok share link, resolve the video with tiktok.app.v3.fetch_one_video_by_share_url_v2, save the raw detail, convert the detail into a snapshot with snapshot.py, and merge the snapshots into video-review.csv with batch_snapshot_csv.py. With video-review.csv, AI can group topics, compare metrics over similar observation windows and shortlist videos for a closer look.
Descriptions and metrics cannot answer questions about speech, visuals or audience feedback; for those questions, collect the video, a transcript or the comments of the selected videos. To evaluate sales, use the campaign’s conversion report.
Which evidence does your question require?
Check comparability before asking AI to summarize
- Verify each video’s identity first, so that a resolved share link does not silently change the target.
- Check the actual collection and publication times. A new video and a long-established video cannot be ranked as campaign winners by unmatched totals.
- Keep failed roster targets on the roster; do not substitute newly searched popular videos.
For example, in a hypothetical pair, video A has 1,000 plays and video B has no play value: you cannot say that A was watched more, and A’s 1,000 plays do not mean 1,000 distinct viewers. A description saying “new product demo” does not show that viewers find the product effective.
video-review.csv includes selected and selection_reason columns for human review. Record each inclusion or exclusion reason before the AI analysis. Editing or re-exporting saved files adds no query. Save another observation of the same video as a separate round, so one video is not counted as two sources. batch_snapshot_csv.py does not carry the human review columns into a fresh export: keep the reviewed copy and reconcile the two files by video ID. New blank review columns do not mean the earlier decisions were migrated.
For example, the same video has 20 shares on Monday and 32 on Friday: report “12 more shares between these snapshots,” with the video ID and both query times. To learn why viewers shared the video, look for specific comments. Keep “the description mentions folding steps” and “shares increased” as two separate observations.
What makes the AI output usable?
Require the AI output to give, for each topic, the video IDs and exact description quotes, the actual counters, the unknowns and the questions the material cannot answer. Check each claim against the originals: the quotation is real, the figures come from the correct row, no zeros are invented, and the output does not claim to have seen images or comments. Remove an unsupported statement or mark the statement unresolved; do not ask the model to invent support.
Steps 1–9 below cover two routes: saved files (steps 1–8) and MCP result reading (step 9). Reuse existing files for offline export. When a tool already retained a result, read the retained result before buying the same detail again to expand a preview. snapshot.py and batch_snapshot_csv.py require complete REST originals; an agent projection is a different input.
Fix the deliverable and spending scope
Hand over the raw details, the verifiable snapshots, the review CSV and a short analysis that states the target roster, the observation times, the failures and the evidence limits. The Python conversion runs locally; collection is a separate paid step. Each selected video needs one detail query. Comments, transcription, retries and model costs are separate, and none runs automatically.
Sources: the local backend input contracts and observed output contracts of the actions named below. The steps were tested with offline fixtures; the ChatGPT steps were not tested against a live ChatGPT connection or a video-viewing session.
1. Prepare a share link and scope
Resolve one TikTok share link into the video ID, caption, author and metric snapshot. Do not collect comments or every video of the author automatically. Inspect data:tiktok.app.v3.fetch_one_video_by_share_url_v2 at the free /v1/capabilities/inspect endpoint for the current contract and price.
2. Save the raw detail
Replace the share_url placeholder with the full link. snapshot.py and batch_snapshot_csv.py both reuse the same detail response. Save each response in a new directory. See BeatAPI pricing for the detail query.
On HTTP failure, keep the error and stop. The detail action returns one video and has no pagination. The resource URL lists in the response describe renditions or mirrors of the same video, not additional videos.
3. Project a comparable metric record
Save the script below as snapshot.py. snapshot.py stores the absolute source path and the SHA-256 of the original bytes. The script reads data.aweme_details, checks for success, exactly one video and a numeric-string ID, and creates a new JSON snapshot. Missing values stay distinct from zero, and earlier snapshots are never overwritten.
4. Run and inspect the artifact
Check the output ID against the original video, and keep the raw detail, the collection time and the request_id. caption comes from desc: caption is the post description, not a spoken transcript. metrics keeps likes, comments, shares, favorites and plays apart and does not estimate unique viewers.
5. Bound subsequent queries
Re-exporting local JSON adds no query charge. A later snapshot needs a new query and a new filename. For comments, pass the resulting aweme_id to the comment action under a separate page and cost budget. Never substitute the author’s sec_uid for aweme_id. Playback URLs can expire; archiving a playback URL is neither permanent hosting nor permission to download.
6. Failure handling and acceptance
A business failure, no results, multiple videos and an invalid ID each stop snapshot creation, and an existing destination is never overwritten. Check that missing values are null, that zero stays zero, and that only the requested video is processed.
IDs and short links · Metrics and comment counts
7. Build a review sheet for a selected group of videos
When your team has a list of campaign video links, freeze the list; do not replace the list with newly searched popular content. Save each detail and snapshot with the actual query time, then merge the successful snapshots into one CSV for editorial review. Keep a separate roster of failed targets with their raw errors; batch_snapshot_csv.py stops on any invalid input instead of silently dropping the target. The result compares the selected videos only and is not a platform-wide popularity chart.
Create snapshots.json with one entry per saved snapshot: the file, the previously confirmed video ID and the actual query time. Budget one detail query per target; retries, comments and other actions are separate. The conversion below runs entirely offline and collects nothing.
Save the script below as batch_snapshot_csv.py and run python3 batch_snapshot_csv.py snapshots.json video-review.csv. batch_snapshot_csv.py accepts one observation per video, rereads and hashes each original response, matches every projected field back to the original response, verifies identity and integer counters, preserves missing values and provenance, and adds selected and selection_reason columns for human review. Before ranking, account for publication age and observation windows. Plays are not unique people and favorites are not purchases. To study change, keep another round in a separate table; two observations of one video must not count as two videos.
If a raw file changed, or a snapshot’s caption, author, identifier, request ID or metric was edited, batch_snapshot_csv.py stops the whole export before creating the CSV. An older snapshot without source_file/source_sha256 must be regenerated from the saved detail, at no query cost. Keep each raw file at the recorded absolute path. The checks establish local consistency only; if both the raw data and the provenance are changed together, the checks cannot detect it. The collection time remains the observation time you recorded separately.
8. Give ChatGPT the right TikTok material
To analyze TikTok videos with ChatGPT, give ChatGPT the material that answers your question:
If the ChatGPT session already has a configured, working data tool, use the client setup guide to pick the action, and verify the source in the execution log. With saved files, follow the steps below.
The saved-file route needs no connected MCP server:
- Complete the conversions above and verify the selected video IDs.
- Review which public content you intend to share, then attach
video-review.csvmanually in a ChatGPT conversation that supports file attachments. Never upload API keys, authorization headers, cookies or unrelated raw records. - If the conversation does not support attachments, paste only the selected review rows.
Attaching the file authorizes no further platform query and no automatic upload by an agent.
Send the instruction below together with the selected rows:
Check the reply by hand:
- Compare every quotation with the CSV caption. If spreadsheet-safe escaping added a leading apostrophe, compare the quotation with the saved snapshot and the original
desc. - Match each ID and collection time to the ID’s row.
- Compare all five counters with the same row.
Remove any unsupported claim instead of asking the model to invent a missing answer. The CSV’s comment count is not a sample of comment text, and an empty caption allows a metric-only row, not a guessed topic. The result reviews your selected records, not the whole account or platform.
If the real question is “what does the speaker say?”, stop the CSV route and get an authorized transcript or a separately verified transcription workflow. If the question is “what are commenters complaining about?”, collect actual comment text under a separate collection and spending scope; the detail result alone does not answer the question. The saved-file route does not cover direct ChatGPT-to-BeatAPI MCP authentication and execution, and an endpoint address or a connection badge does not prove that such an integration works.
Reusing the saved CSV makes no new BeatAPI request. Count details, comments and transcription separately using actual usage. See BeatAPI pricing.
9. Use an agent preview without buying the same detail again
The remote MCP entry is https://beatapi.io/mcp; the direct REST collection above uses https://api.beatapi.io. Store the Bearer key in your client’s supported secret configuration, not in a chat prompt or a checked-in file. Client integration instructions differ by client. Seeing the tools or completing a free Inspect does not prove that authenticated execution works.
For the one-video job, inspect data:tiktok.app.v3.fetch_one_video_by_share_url_v2. After the specific target and the current price are approved, use the generic Run template below:
A preview may shorten text even when the preview shows the only video. A preview is not a transcript, a comment page or proof of complete fields. max_items controls the view and does not make the platform call cheaper. The detail action is synchronous, so do not build a polling loop. A timeout does not authorize another paid start: if an approved retry of the same logical operation is necessary, keep the same idempotency_key and identical input. A genuinely new snapshot needs its own scope and budget.
If the actual response supplies result_ref, copy the result_ref request ID and expiry. Before the expiry, with the same account, request only the evidence you need:
The field paths in the request above come from the published output contract of data:tiktok.app.v3.fetch_one_video_by_share_url_v2. items[] is the lifted result list; the REST raw archive above contains data.aweme_details instead. Do not pass the projected Run result into snapshot.py or batch_snapshot_csv.py: both converters require the complete direct REST envelope. Choose the saved-file route above when you need the auditable CSV, or keep and review the agent projection separately. Do not pay for a second detail just to change the presentation.
The checked backend keeps eligible trimmed results for one hour, scoped to the account; follow the returned expiry. Reading a retained result does not repeat the platform query. A missing result_ref, result_ref_unavailable or result_expired means stop; do not switch accounts or start again. Export the evidence you need before the expiry; the cache is not an archive.
To accept the agent result, record the actual start request ID and price, the one expected video ID, the projection paths, the full caption, the five metric states and the remaining evidence limits. A projection sets truncated=true whenever the projection omits other fields, so truncated=true alone does not mean the selected caption was cut. Check the view, the item counts, string trimming and fields_not_found; a field that matches somewhere is not a per-row completeness guarantee. The review CSV above adds one state column per metric: missing, null, number or digit_string. Zero remains a value, not an absence. statistics_state distinguishes a missing statistics object from an explicit null object. Rebuild an older CSV from the saved originals at no platform-query cost.
To compare context usage, run the same saved records through the same model and compare the actual input tokens. See BeatAPI pricing for new data requests.

