InstagramリールAPIチュートリアル

Instagramリールのデータをスクレイピングする方法:APIの使い方

ユーザー名から公開Instagramリールを収集する、本番向けのワークフローを構築します。キャプション、メディア、音源、表示されている指標、ページネーション、指標のスナップショットまでを扱います。

SocQ2026年7月19日更新約9分で読めます

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

クリエイターごとに、次のことを行います。

  1. 直近の妥当な期間を収集する。
  2. 利用できる場合は、created_at でレコードを並べ替える。
  3. 繰り返し返される古いレコードを、新たな発見として扱わなくする。
  4. リールIDでアップサートする。
  5. 収集が成功した場合に限り、スナップショットを追加する。
  6. クリエイターの最後に成功した実行を、タスクの送信とは別に追跡する。

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が、永久に使えると思い込まないでください。

プロダクトでメディアを長期に保持する必要がある場合は、次のようにします。

  1. アセットの保存が許可されているかを確認する。
  2. 目的に必要なメディアだけをダウンロードする。
  3. 元のURLと収集時刻を記録する。
  4. 保持と削除の管理を適用する。
  5. 保存したメディアを安全に配信する。

分析にキャプションと指標しか必要ないなら、大きなメディアファイルを保存しても、価値を増やさないままコストとリスクが増えるおそれがあります。

リールのパフォーマンスを慎重に測定する

有用な派生指標には、次のようなものがあります。

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を見る