Instagramのリールを1件手作業で集めるのは簡単です。しかし、数百人の公開クリエイターにわたって繰り返し使えるデータセットを作るのは、もっと困難です。リールは消えることがあり、指標は変化し、メディアのURLは失効し、表示されるフィールドも投稿ごとに異なります。
このチュートリアルでは、SocQ Instagram Reels APIを使ってユーザー名から公開リールを収集し、非同期タスクをポーリングし、安定したエンティティのフィールドを指標のスナップショットとは別に保存して、モニタリングや分析に向けてデータを準備する方法を説明します。
ひとことで言うと: 公開ユーザー名と、ユーザー名ごとの
results_limitをPOST /v1/instagram/reelsに送信します。返されたtask_idを保存し、タスクのエンドポイントをポーリングして、正規化されたリールのレコードをdata.results.itemsから読み取ります。現在のエンドポイントが受け付けるのは、ユーザー名であり、個別のリールのURLではありません。
Instagram公式APIか、公開リールAPIか
ユーザーが対応しているプロフェッショナルアカウントを認可し、アプリケーションが、投稿の公開、インサイト、コメント管理、そのほか許可が必要な操作を必要とする場合は、Metaの公式Instagram APIが適切な選択です。
これは、不特定多数の一般ユーザーの公開プロフィールを収集するための汎用的なエンドポイントではありません。公式のアクセスは、アカウントの種類、権限、トークン、アプリ審査、選択したInstagramの製品によって決まります。認可を伴うワークフローを設計する前に、最新のInstagram Platformのドキュメントを確認してください。
対応している公開データの読み取りワークフローにはSocQを、アカウントの操作や許可が必要なインサイトにはMetaの公式APIを使ってください。公開データAPIを使っても、Instagramの利用規約、プライバシーの権利、知的財産のルールを無視してよいことにはなりません。
Instagramリールのタスクを送信する
現在のエンドポイントは、1件以上の公開ユーザー名を受け付けます。
curl -X POST "https://api.socq.ai/v1/instagram/reels" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"usernames": ["natgeo", "instagram"],
"results_limit": 100
}'
送信する前に、ユーザー名を正規化してください。
- 先頭の
@を取り除く。 - 空白を削除する。
- プロフィールURLは、入力レイヤーでユーザー名に変換する。
- 大文字小文字を区別せずに重複を排除する。
- 空の値は拒否する。
results_limit は、ユーザー名ごとに要求する結果の上限です。どのクリエイターについても、その件数の公開リールが取得できることを保証するものではありません。
非同期タスクをポーリングする
返された task_id を保存して、ポーリングします。
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
queued と running は正常な状態として扱います。短い間隔でのループによるポーリングではなく、指数バックオフを使ってください。タスクが成功したら、data.results.items を読み取ります。has_more がtrueの場合は、next_cursor で次のページを要求します。
堅牢なワーカーは、次のものを保存してください。
- バッチID。
- SocQのタスクID。
- 送信したユーザー名。
- 送信と完了の時刻。
- 終了状態とエラーのカテゴリ。
- 最後に処理した結果のカーソル。
この状態を保存しておけば、完了した収集を再送信せずに、ワーカーを再開できます。
リールのレスポンスを理解する
正規化されたリールのレコードは、次のような形になります。
{
"id": "3138424916027781494",
"platform": "instagram",
"resource": "reels",
"type": "reel",
"shortcode": "CtjoC2BNsB2",
"url": "https://www.instagram.com/reel/CtjoC2BNsB2/",
"caption": "A public Instagram Reel.",
"author": {
"id": "123",
"username": "natgeo",
"name": "National Geographic",
"url": "https://www.instagram.com/natgeo"
},
"metrics": {
"likes_count": 21904,
"comments_count": 502,
"views_count": 284110,
"plays_count": 284110
},
"media": [],
"duration_seconds": 42,
"audio": {
"title": "Original audio",
"artist": "natgeo"
},
"hashtags": [],
"mentions": [],
"created_at": "2026-07-08T16:05:00",
"collected_at": "2026-07-19T10:00:00",
"extra": {}
}
エンティティのキーには id を優先し、代わりとして shortcode を使ってください。追跡のために url は保持します。指標、メディア、音源、一部のプロフィールのフィールドは取得できない場合があります。欠損値を0や空文字列に変換せず、null許容として扱ってください。
エンティティと指標のスナップショットを分けて保存する
リールのアイデンティティとリールの指標は、変化する速さが異なります。
エンティティのテーブルには、次の項目を保存できます。
reel_id
shortcode
canonical_url
author_id
caption
created_at
duration_seconds
audio
first_seen_at
last_seen_at
スナップショットのテーブルには、次の項目を保存できます。
reel_id
collected_at
likes_count
comments_count
views_count
plays_count
これにより、毎日のモニタリングでリールのエンティティが重複して作られるのを防ぎつつ、時間の経過に伴う増加を記録できます。
どちらかのスナップショットに指標がない場合は、増加を計算しないでください。非表示の数値は0ではありません。また、views_count と plays_count を、すべてのソースが同じ定義であるかのように比較するのも避けてください。
差分のリールモニターを構築する
最もシンプルで信頼できるモニターは、次のとおりです。
Creator registry
↓
Daily or hourly collection schedule
↓
Async task polling
↓
Schema validation
↓
Upsert Reel entity by id
↓
Append metric snapshot
↓
Alerts and reports
クリエイターごとに、次のことを行います。
- 直近の妥当な期間を収集する。
- 利用できる場合は、
created_atでレコードを並べ替える。 - 繰り返し返される古いレコードを、新たな発見として扱わなくする。
- リールIDでアップサートする。
- 収集が成功した場合に限り、スナップショットを追加する。
- クリエイターの最後に成功した実行を、タスクの送信とは別に追跡する。
Instagramのフィードはランキングされており、ソースの提供状況は変わることがあります。このエンドポイントを、完全な過去のアーカイブが保証されたものとして扱わないでください。
ページネーションを使ったPythonの例
import time
import requests
BASE = "https://api.socq.ai/v1"
HEADERS = {
"Authorization": f"Bearer {SOCQ_API_KEY}",
"Content-Type": "application/json",
}
created = requests.post(
f"{BASE}/instagram/reels",
headers=HEADERS,
json={"usernames": ["natgeo"], "results_limit": 200},
timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["task_id"]
delay = 2
while True:
response = requests.get(
f"{BASE}/tasks/{task_id}",
headers=HEADERS,
timeout=30,
)
response.raise_for_status()
task = response.json()["data"]
if task["status"] == "succeeded":
break
if task["status"] in {"failed", "cancelled"}:
raise RuntimeError(task)
time.sleep(delay)
delay = min(delay * 1.5, 15)
items = task["results"]["items"]
cursor = task["results"].get("next_cursor")
while cursor:
page = requests.get(
f"{BASE}/tasks/{task_id}",
headers=HEADERS,
params={"limit": 100, "cursor": cursor},
timeout=30,
)
page.raise_for_status()
results = page.json()["data"]["results"]
items.extend(results["items"])
cursor = results.get("next_cursor")
本番では、タイムアウト、429、リトライ可能な5xxのレスポンスに対して、上限のあるリトライを追加してください。エラーのカテゴリを確認せずに、失敗した入力を自動的に再送信しないでください。
保存前にリールのデータを検証する
推奨するチェックは次のとおりです。
platformがinstagramであること。resourceがreelsであること。id、shortcode、urlのうち、少なくとも1つが存在すること。- 取得できる場合は、
author.usernameが、送信したクリエイターと一致すること。 - 数値が、負でない数値かnullであること。
created_atとcollected_atが、タイムスタンプとして解析できること。- メディアのエントリを、恒久的なアセットではなく、ソースへの参照として扱うこと。
無効なレコードは、生のタスクと検証エラーとともに、隔離用のテーブルに保管してください。フィールドを黙って変換すると、上流の変更が見えなくなります。
メディアのURLは恒久的な保存先ではない
リールの動画、画像、カバー、アバターのURLは、署名付きだったり、変換されたり、レート制限されたり、変更されたりすることがあります。今日収集したURLが、永久に使えると思い込まないでください。
プロダクトでメディアを長期に保持する必要がある場合は、次のようにします。
- アセットの保存が許可されているかを確認する。
- 目的に必要なメディアだけをダウンロードする。
- 元のURLと収集時刻を記録する。
- 保持と削除の管理を適用する。
- 保存したメディアを安全に配信する。
分析にキャプションと指標しか必要ないなら、大きなメディアファイルを保存しても、価値を増やさないままコストとリスクが増えるおそれがあります。
リールのパフォーマンスを慎重に測定する
有用な派生指標には、次のようなものがあります。
engagement_per_play =
(likes + comments) / plays
daily_play_growth =
(current_plays - previous_plays) / elapsed_days
指標を計算するのは、その入力がそろっている場合だけにしてください。クリエイターを比較するときは、一貫した期間と収集スケジュールを使います。2時間前に公開されたリールを、2週間観測されたリールと、時間の正規化なしにランキングしてはいけません。
公開されている数値は、表示されているスナップショットであり、監査された分析結果ではありません。自社で所有するプロフェッショナルアカウントでは、許可を得たパフォーマンスのデータとして、公式のInstagramインサイトのほうが適しています。
よくある失敗ケースに対処する
| ケース | 推奨する対処 |
|---|---|
| 無効なユーザー名 | 送信前に拒否する |
| 非公開アカウント | 取得不可としてマークする。回避しない |
| 名前が変更されたアカウント | 手動で解決するか、レジストリを更新する |
| 公開リールがない | 空の成功した観測として保存する |
| タスクのタイムアウト | 再送信する前に、ポーリングをリトライする |
| 指標の欠損 | nullのまま保持する |
| リールの重複 | IDまたはショートコードでアップサートする |
| 失効したメディアのURL | ユースケースが許す場合に限って更新する |
空の成功した結果と失敗したタスクは、運用上、異なる状態です。
責任ある利用
- 正当な目的に必要な公開データだけを収集する。
- 非公開プロフィールにアクセスしたり、制御を回避したりしない。
- 個人に対するセンシティブなプロファイリングは避ける。
- 削除、プライバシー、知的財産に関する要請を尊重する。
- APIキー、エクスポート、メディアを安全に管理する。
- Instagramの利用規約と、プロバイダーとの契約を確認する。
- アカウントの操作には、Metaの公式の認可を使う。
SocQが提供するのは、技術的な収集のワークフローであり、コンテンツに関する追加の権利ではありません。
Instagram Reels APIのよくある質問(FAQ)
SocQで、リールのURLを直接指定してスクレイピングできますか?
現在のReelsエンドポイントが受け付けるのは、公開ユーザー名であり、個別のリールのURLではありません。そのクリエイターの、取得できる公開リールを返します。
エンドポイントは動画ファイルを返しますか?
取得できる場合は、正規化された公開メディアへの参照を返します。URLは、恒久的なダウンロード先ではなく、一時的なソースへの参照として扱ってください。
閲覧数と再生数は常に取得できますか?
いいえ。Instagramが指標を非表示にしたり、省略したりすることがあります。欠損値は、nullのまま保持してください。
非公開アカウントのリールを収集できますか?
いいえ。公開データのワークフローで、非公開アカウントの制御を回避してはいけません。
リールの重複を避けるにはどうすればよいですか?
公開されているリールのIDをキーとして優先し、代わりとしてショートコードを使います。指標は、別のスナップショットのテーブルに保存してください。
代わりにMetaの公式Instagram APIを使うべきですか?
認可されたプロフェッショナルアカウント、投稿の公開、インサイト、アカウントの操作には、公式APIを使ってください。SocQは、対応している公開データの読み取りワークフローに使います。
INSTAGRAM API
公開InstagramのURLでワークフローを試す
公開データの入力を送信すると、取得元をたどれるコンテキスト付きの正規化レコードを受け取れます。
InstagramのAPIを見る