> 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 build a Channels account’s video directory and select useful research examples?

> Collect account videos, distinguish listing from keyword search, and use saved pages and separate engagement rankings to select research examples.

To export a Channels account’s videos, pass the account’s `@finder` ID as `username` to `wechat_channels.v2.fetch_user_videos`, save each response page, and run `export_channel_pages.py` on the saved pages to produce `selected-videos.csv`, `metric-rankings.csv` and `coverage.json`. When you only need one creator’s videos about a particular product, use the account-scoped keyword search `wechat_channels.v2.fetch_search_channel_videos` instead.

## Choose listing or account search

| Goal                                      | Method                                                                         | Next page                                                                           |
| ----------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| Collect one account's published videos    | `data:wechat_channels.v2.fetch_user_videos` with `raw:false`                   | Check `up_continue` and return the received `last_buffer` as the next `last_buffer` |
| Find one account's videos about a keyword | `data:wechat_channels.v2.fetch_search_channel_videos` with account and keyword | Start with an empty `cursor`, then use returned `next_cursor`                       |

Both methods start from a verified finder username. With an `sph…` short ID or a video share link, use the [identifier workflow](/faq/wechat-channels-identifiers) to choose the right route. If you already have a canonical account identifier, reuse the identifier.

## Build a table for selecting examples

1. **Set the scope.** For example, collect the past month's videos with descriptions, publication times, video IDs and available engagement counts.
2. **Retrieve the list.** Send `action:"wechat_channels.v2.fetch_user_videos"` to `POST /v1/social-data/call` with the verified `username`, `raw:false` and an initial `last_buffer:""`. `data.videos` holds the videos; the response also carries the account and continuation fields.
3. **Continue for the same account.** Save each request, response and collection time, then send the `last_buffer` returned by the latest page as the next `last_buffer`. Keep the account and `raw:false` unchanged. If a request fails, keep the last successful page for review.
4. **Select videos from the table.** Process the saved pages with `export_channel_pages.py` below. Review topics and compare like and share counts separately, then retrieve details or [comments](/faq/wechat-channels-comments) for the examples worth investigating.

To hand the task to an assistant connected to BeatAPI, use this instruction:

> Collect this Channels account's videos from the past month, retaining descriptions, publication times, video IDs and returned like/share counts. List the top 10 separately by likes and shares within this sample. Select product-launch examples and explain the selection reasons and actual coverage.

Check the date range with `create_time` before reviewing topics. Rankings describe the collected set only; weigh publication age and content alongside cumulative counts.

## Which output files should I read?

* `selected-videos.csv`: selected records grouped by usable video ID for browsing and filtering.
* `video-observations.csv`: all returned observations for reviewing repeats and changes.
* `metric-rankings.csv` / `.json`: separate rankings by exact like and share counts.
* `coverage.json`: actual observation and selection counts, stop reason, missing values and conflicts.

A video with unavailable counters can still be useful content; keep the video outside the numerical ranking. The current definition of `read_count` does not support labeling `read_count` as another creator’s play count. Keep the field name `read_count` and use verified likes or shares for engagement research.

## Find a topic without reviewing the whole directory

Use [account-topic search](/guides/wechat-channels-channel-search): keep the account and the keyword unchanged and pass `next_cursor → cursor`. Account-topic search covers one account; use a separate WeChat search route for wider discovery.

Keep separate pagination state for lists, search and comments. Comments use `data:wechat_channels.v2.fetch_video_comments`, and root comments and one parent comment’s replies paginate in separate branches. See [comment export](/faq/wechat-channels-comments).

The saved-page exporter and the ranking method follow below. Each batch accepts 1–20 pages. When a batch stops at the page cap, the batch’s coverage ends at the cap; collect and merge further history in separate batches. See current [pricing](https://beatapi.io/pricing); processing saved pages locally needs no new retrieval.

## Export saved account-video pages to a reviewable table

For a known finder username, use `fetch_user_videos`, not the account-topic search action above. With an explicit `raw:false`, the response contains `data.username`, `videos`, `up_continue` and `last_buffer`. The published video fields include `id`, `title`, `create_time`, `read_count`, `like_count`, `fav_count`, `forward_count`, `comment_count` and `location`. `export_channel_pages.py` keeps each field’s raw value and whether the field was present; the exporter does not equate `read_count` with verified unique viewers and does not turn absent counters into zero.

Reuse a valid finder username that [profile-link evidence](/faq/wechat-account-profile) already provides. Start with an empty `last_buffer`, keep the account and `raw:false` unchanged, and record the actual rows per page. Calculate the list cost from the number of page requests and current [pricing](https://beatapi.io/pricing).

Save each actual request, HTTP status, response and collection time. In `pages.json`, the `last_buffer` of the second and each later page must exactly match the `last_buffer` returned in the previous response. The example below shows the format; the example is not a recorded response:

```json
[{"action":"wechat_channels.v2.fetch_user_videos","params":{"username":"v2_123abc@finder","raw":false,"last_buffer":""},"http_status":200,"collected_at":"2026-11-17T09:00:00Z","response_file":"page-1.json"}]
```

Save the script below as `export_channel_pages.py` and run `python3 export_channel_pages.py pages.json channel-review`. Response paths are relative to `pages.json`; use a new output directory. Run the script only on saved full JSON, not on a trimmed preview. The script sends no requests.

```python
import csv,hashlib,json,pathlib,re,sys
from datetime import datetime
manifest,out=map(pathlib.Path,sys.argv[1:3]);original=manifest.read_bytes();pages=json.loads(original)
if not isinstance(pages,list) or not 1<=len(pages)<=20:raise ValueError('Supply 1–20 saved pages')
ACTION='wechat_channels.v2.fetch_user_videos';rows,sources,ids,rids,cursors=[],[],set(),set(),set();expected='';account=None;stop=None;unsafe=0
def cell(v):
 if v is None:return ''
 v=str(v);return "'"+v if v.startswith(('=','+','-','@','\t','\r','\n')) else v
def identity(v):
 if isinstance(v,str) and re.fullmatch(r'[0-9]{1,32}',v):return v,'string'
 if type(v) is int and 0<=v<=9007199254740991:return str(v),'safe_integer'
 return None,'unsafe_or_invalid'
for i,e in enumerate(pages,1):
 if stop is not None:raise ValueError('Pages supplied after stop condition')
 params=e.get('params');u=params.get('username') if isinstance(params,dict) else None
 if e.get('action')!=ACTION or not isinstance(params,dict) or set(params)!={'username','raw','last_buffer'} or params['raw'] is not False:raise ValueError('Use exact raw:false list request')
 if not isinstance(u,str) or not 10<=len(u)<=256 or not re.fullmatch(r'v2_[0-9a-fA-F]+@finder',u):raise ValueError('Invalid finder username')
 if account is None:account=u
 if u!=account or params['last_buffer']!=expected:raise ValueError('Account or cursor chain changed')
 cursors.add(expected)
 t=e.get('collected_at')
 if not isinstance(t,str) or datetime.fromisoformat(t.replace('Z','+00:00')).tzinfo is None:raise ValueError('Record actual collection time with timezone')
 http=e.get('http_status')
 if type(http) is not int or not 100<=http<=599:raise ValueError('Invalid HTTP status')
 raw=(manifest.parent/e['response_file']).read_bytes();body=json.loads(raw)
 if not isinstance(body,dict):raise ValueError('Expected response object')
 source={'index':i,'request':e,'sha256':hashlib.sha256(raw).hexdigest(),'raw_file':'raw-%02d.json'%i};sources.append((source,raw))
 if http!=200:
  error=body.get('error')
  if not isinstance(error,dict) or not isinstance(error.get('code'),str) or not error['code'].strip():raise ValueError('Expected gateway error')
  source.update(error_code=error['code'],request_id=error.get('request_id'));stop='gateway_failed';continue
 data=body.get('data');rid=body.get('request_id')
 if body.get('status')!='succeeded' or body.get('action')!=ACTION or body.get('error') is not None or not isinstance(data,dict):raise ValueError('Wrong successful envelope')
 if not isinstance(rid,str) or not rid.strip() or rid in rids:raise ValueError('Missing or duplicate request ID')
 rids.add(rid);source['request_id']=rid
 if data.get('username')!=account or not isinstance(data.get('videos'),list):raise ValueError('Missing account echo or videos array')
 videos=data['videos'];source['reported_count']=data.get('count');source['observations']=len(videos)
 for j,v in enumerate(videos):
  if not isinstance(v,dict) or (v.get('username') is not None and v['username']!=account):raise ValueError('Video author mismatch')
  object_id,state=identity(v.get('id'));duplicate=object_id in ids if object_id is not None else False
  if object_id is None:unsafe+=1
  else:ids.add(object_id)
  row={'account':account,'object_id':object_id,'id_state':state,'id_raw':json.dumps(v.get('id')),'duplicate_observation':str(duplicate).lower(),'title':v.get('title'),'collected_at':t,'request_id':rid,'source_index':i,'video_index':j}
  if row['title'] is not None and not isinstance(row['title'],str):raise ValueError('Invalid title')
  for field in ['create_time','read_count','like_count','fav_count','forward_count','comment_count','location']:
   row[field+'_raw']=json.dumps(v.get(field),ensure_ascii=False);row[field+'_present']=str(field in v).lower()
  rows.append(row)
 flag=data.get('up_continue');cursor=data.get('last_buffer');source.update(up_continue=flag,last_buffer=cursor)
 if type(flag) not in (bool,int) or flag not in (0,1):stop='unsupported_more_flag'
 elif not flag:stop='provider_end'
 elif not videos:stop='empty_page_with_more'
 elif not isinstance(cursor,str) or not cursor or not re.fullmatch(r'[A-Za-z0-9+/=_-]+',cursor):stop='missing_or_invalid_cursor'
 elif cursor in cursors:stop='repeated_cursor'
 else:expected=cursor
if stop is None:stop='saved_page_limit'
columns=['account','object_id','id_state','id_raw','duplicate_observation','title','collected_at','request_id','source_index','video_index']
for field in ['create_time','read_count','like_count','fav_count','forward_count','comment_count','location']:columns.extend([field+'_raw',field+'_present'])
groups={}
for row in rows:
 if row['object_id'] is not None:groups.setdefault(row['object_id'],[]).append(row)
selected,conflicts=[],[]
for object_id,observations in groups.items():
 latest=max(datetime.fromisoformat(r['collected_at'].replace('Z','+00:00')) for r in observations)
 candidates=[r for r in observations if datetime.fromisoformat(r['collected_at'].replace('Z','+00:00'))==latest]
 def values(r):return {k:r[k] for k in ['title']+[f+'_raw' for f in ['create_time','read_count','like_count','fav_count','forward_count','comment_count','location']]+[f+'_present' for f in ['create_time','read_count','like_count','fav_count','forward_count','comment_count','location']]}
 if any(values(r)!=values(candidates[0]) for r in candidates[1:]):
  conflicts.append({'object_id':object_id,'reason':'conflicting_newest_observations','sources':[{'source_index':r['source_index'],'video_index':r['video_index']} for r in candidates]})
 else:selected.append(candidates[0])
ranked=[];ranking_coverage={}
def count_state(row,metric):
 if row[metric+'_present']!='true':return None,'missing'
 value=json.loads(row[metric+'_raw'])
 if value is None:return None,'null'
 if type(value) is int:
  return (value,'exact_integer') if 0<=value<=9007199254740991 else (None,'unsafe_or_negative_number')
 if isinstance(value,str) and re.fullmatch(r'[0-9]{1,64}',value):return int(value),'exact_digit_string'
 return None,'unsupported_value'
for metric in ['like_count','forward_count']:
 entries=[]
 for row in selected:
  number,state=count_state(row,metric)
  entries.append({'object_id':row['object_id'],'title':row['title'],'collected_at':row['collected_at'],'metric':metric,'value_raw':row[metric+'_raw'],'value_state':state,'exact_count':str(number) if number is not None else '', 'rank':'','request_id':row['request_id'],'source_index':row['source_index'],'video_index':row['video_index'],'_number':number})
 entries.sort(key=lambda e:(e['_number'] is None,-e['_number'] if e['_number'] is not None else 0,e['object_id']))
 previous=None;rank=None;eligible=0
 for entry in entries:
  number=entry.pop('_number')
  if number is not None:
   eligible+=1
   if number!=previous:rank=eligible
   entry['rank']=rank;previous=number
 ranked.extend(entries)
 ranking_coverage[metric]={'eligible_videos':eligible,'unranked_videos':len(entries)-eligible,'tie_rule':'competition ranks; equal counts share rank','scope':'selected usable IDs only; not plays or unique viewers'}
out.mkdir(mode=0o700,exist_ok=False)
with (out/'video-observations.csv').open('x',encoding='utf-8-sig',newline='') as f:
 w=csv.DictWriter(f,fieldnames=columns);w.writeheader();w.writerows({k:cell(v) for k,v in r.items()} for r in rows)
with (out/'selected-videos.csv').open('x',encoding='utf-8-sig',newline='') as f:
 w=csv.DictWriter(f,fieldnames=columns);w.writeheader();w.writerows({k:cell(v) for k,v in r.items()} for r in selected)
with (out/'metric-rankings.csv').open('x',encoding='utf-8-sig',newline='') as f:
 fields=['object_id','title','collected_at','metric','value_raw','value_state','exact_count','rank','request_id','source_index','video_index']
 w=csv.DictWriter(f,fieldnames=fields);w.writeheader();w.writerows({k:cell(v) for k,v in r.items()} for r in ranked)
(out/'metric-rankings.json').write_text(json.dumps(ranked,ensure_ascii=False,indent=2),encoding='utf-8')
(out/'selection-conflicts.json').write_text(json.dumps(conflicts,ensure_ascii=False,indent=2),encoding='utf-8')
for source,raw in sources:(out/source['raw_file']).write_bytes(raw)
(out/'manifest.json').write_bytes(original)
report={'ranking_coverage':ranking_coverage,'account':account,'sources':[s for s,_ in sources],'stop_reason':stop,'video_observations':len(rows),'distinct_usable_ids':len(ids),'selected_unique_videos':len(selected),'conflicting_ids':len(conflicts),'selection_rule':'latest recorded collection time; equal-time disagreements withheld','unsafe_id_observations':unsafe,'provider_end_seen':stop=='provider_end','all_account_history_verified':False,'media_downloaded':False,'executed_calls':0,'manifest_sha256':hashlib.sha256(original).hexdigest()}
(out/'coverage.json').write_text(json.dumps(report,ensure_ascii=False,indent=2),encoding='utf-8')
if stop=='saved_page_limit':(out/'unexecuted-next-request.json').write_text(json.dumps({'action':ACTION,'params':{'username':account,'raw':False,'last_buffer':expected}},indent=2),encoding='utf-8')
print(json.dumps({'observations':len(rows),'stop_reason':stop,'executed_calls':0}))
```

`video-observations.csv` has one row per returned observation, not one row per unique video. A repeated usable ID is flagged instead of silently replacing the earlier engagement counts. `coverage.json` states the distinct usable IDs, the unsafe-ID rows, the exact source indexes and the stop condition. The `*_present` and `*_raw` columns keep a missing value and a null value distinct. A raw numeric ID beyond 2^53−1 is quarantined with no usable `object_id`; converting such an ID to a string after possible gateway rounding does not restore the lost digits. Do not use quarantined rows for follow-up detail or comment requests, and do not deduplicate quarantined rows by title.

`provider_end` means the saved pagination chain reached the end the provider reported; `provider_end` does not prove that the account history is complete. An empty page that reports more pages, a repeated or missing cursor and an unknown continuation flag each stop the batch without a next request. A gateway error on the final page keeps the earlier observations and the error evidence. A schema, identity or chain error rejects the whole batch before any output is created. When only the saved-page cap stopped collection, `unexecuted-next-request.json` holds the continuation request but neither authorizes nor executes the request. Changing the account or the raw mode starts a new chain.

The CSV files deliberately exclude media URL tokens and decode keys. Full raw responses can contain the tokens and keys, so the new output directory is private by default; keep the originals local, and review and redact any copy you share. The workflow does not download, decrypt, publish or send media. An interrupted file write is not a completed export: after resolving the interruption, write to a new output directory and never overwrite the original evidence.

## Which file gives one selected row per video?

Use `selected-videos.csv` for the selected subset, and keep `video-observations.csv` as the full log of returned observations. Selection groups only usable IDs and takes the latest recorded collection time, not the last position in file order. When the two newest observations have identical selected content and metric fields, the exporter takes the first source reference; contradictory newest values are withheld and written to `selection-conflicts.json`. Older observations stay in the log. Videos from different accounts are never merged.

`coverage.json` reports `selected_unique_videos`, `conflicting_ids` and `unsafe_id_observations` separately. `selected-videos.csv` can have fewer rows than there are distinct usable IDs; inspect the excluded IDs before calling the deliverable complete. The exporter never invents a zero row for an unsafe or conflicting item. Collection time is the request evidence you supplied, not the video’s publication time, and does not prove that the platform refreshed the metrics at that moment. `selected-videos.csv` is not an equal-age ranking and does not claim complete history.

## Can I report read_count as another creator's video plays?

Not from the `fetch_user_videos` contract alone. The checked account-video schema lists `read_count` among the reported interaction counters but does not define whether `read_count` counts unique viewers, playbacks, repeat views or completions. Keep the original name `read_count`. Do not rename `read_count` to `plays`, derive a completion rate from `read_count` or infer private creator-dashboard analytics. An absent field is not zero, and another provider’s lack of a field does not establish what `fetch_user_videos` returns.

For the actual task “which of the sampled videos have the most reported likes or forwards?”, `export_channel_pages.py` creates `metric-rankings.csv` and `metric-rankings.json`. The exporter ranks `like_count` and `forward_count` separately, using the conflict-aware selected videos already built from the original pages. No new query, paid single-video lookup or manual field guessing is required.

## How are incomplete or formatted counters ranked?

| Saved value                                                                                  | Treatment                                                                                 |
| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Integer 0 or original digit string "0"                                                       | Exact zero, eligible for ranking                                                          |
| Safe nonnegative JSON integer or 1–64 ASCII digit string                                     | Eligible; preserve the original representation and exact decimal count                    |
| Missing or null                                                                              | Keep a row with its state and no rank; never replace it with zero                         |
| A formatted value such as "10万+", "1.2k", decimal, boolean, negative or unsafe numeric value | Retain raw value, leave unranked; do not invent a multiplier or precise lower-bound score |
| Equal exact counts                                                                           | Same competition rank: 1, 1, 3; object ID only makes display order deterministic          |
| Conflicting newest observations for one ID                                                   | Excluded before ranking and retained in selection-conflicts.json                          |

The newest selected observation decides eligibility. If the newest observation has no count, the exporter does not fall back to an older count to fill the leaderboard. An unsafe ID is excluded instead of being repaired by converting an already-rounded number to text. `coverage.json` holds each metric’s eligible and unranked totals, so the “top 10” can contain fewer than ten usable rows. An unavailable counter is not evidence of low engagement.

Use `metric-rankings.json` for exact string IDs and large integer strings. If you open `metric-rankings.csv` in a spreadsheet, import `object_id` and `exact_count` as text to avoid automatic rounding; CSV quoting alone does not guarantee precision. `value_raw`, `request_id`, `source_index` and `video_index` let you check each rank against the archived raw page. Hashes detect changed local bytes; hashes do not detect forged observations.

## What does a ranked result prove, and what should a report say?

A ranking orders the reported counters within the selected, successfully collected sample, not across every video on the account or the platform. Keep `collected_at` next to each value, and review publication age, observation windows and source coverage before comparing performance. A later observation of the same post has had more time to accumulate interactions, so comparing different posts requires both the publication time and the collection time. Ranked rows do not establish purchases, unique people, paid reach or causation.

Use wording such as “Among the 18 usable video IDs in this saved sample, 16 had exact like counts; two were unranked. The largest reported count was … at the listed collection time.” Replace the example counts with the actual counts in `coverage.json`. Do not write “the most watched video” or “top of the whole account” from the ranking table. Ranking saved pages adds zero platform calls; fresh account pages are charged at the current [pricing page](https://beatapi.io/pricing).