Threads API Guide: Access, Publishing & Insights

# 1) Create a media container
curl -X POST "https://graph.threads.net/v1.0/$THREADS_USER_ID/threads" \
  -d media_type=TEXT \
  -d text="Shipping something new today 🚀" \
  -d access_token=$THREADS_TOKEN
# → { "id": "CONTAINER_ID" }

# 2) (Images/video) check the container is ready
curl -G "https://graph.threads.net/v1.0/CONTAINER_ID" \
  -d fields=status,error_message \
  -d access_token=$THREADS_TOKEN
# → { "status": "FINISHED", "id": "CONTAINER_ID" }

# 3) Publish it
curl -X POST "https://graph.threads.net/v1.0/$THREADS_USER_ID/threads_publish" \
  -d creation_id=CONTAINER_ID \
  -d access_token=$THREADS_TOKEN
# → { "id": "POST_ID" }

import os, time, requests

BASE = "https://graph.threads.net/v1.0"
TOKEN = os.environ["THREADS_TOKEN"]
USER_ID = os.environ["THREADS_USER_ID"]

def wait_until_ready(container_id, tries=10):
    for _ in range(tries):
        r = requests.get(f"{BASE}/{container_id}",
                         params={"fields": "status,error_message",
                                 "access_token": TOKEN}).json()
        if r.get("status") == "FINISHED":
            return
        if r.get("status") in ("ERROR", "EXPIRED"):
            raise RuntimeError(r)
        time.sleep(5)
    raise TimeoutError("Container not ready")

def publish(media_type="TEXT", **fields):
    c = requests.post(f"{BASE}/{USER_ID}/threads",
                      data={"media_type": media_type,
                            "access_token": TOKEN, **fields})
    c.raise_for_status()
    container_id = c.json()["id"]
    if media_type != "TEXT":
        wait_until_ready(container_id)
    p = requests.post(f"{BASE}/{USER_ID}/threads_publish",
                      data={"creation_id": container_id,
                            "access_token": TOKEN})
    p.raise_for_status()
    return p.json()["id"]

print(publish(text="Hello from Python 🐍"))
print(publish("IMAGE", image_url="https://example.com/photo.jpg",
              text="New drop"))

// Node.js 18+ (built-in fetch)
const BASE = "https://graph.threads.net/v1.0";
const { THREADS_TOKEN: TOKEN, THREADS_USER_ID: USER_ID } = process.env;
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function call(path, params = {}, method = "GET") {
  const body = new URLSearchParams({ ...params, access_token: TOKEN });
  const url = method === "GET" ? `${BASE}/${path}?${body}` : `${BASE}/${path}`;
  const res = await fetch(url, method === "GET" ? {} : { method, body });
  const json = await res.json();
  if (!res.ok) throw new Error(JSON.stringify(json.error));
  return json;
}

async function publish(fields) {
  const { id } = await call(`${USER_ID}/threads`, fields, "POST");
  if (fields.media_type !== "TEXT") {
    for (let i = 0; i < 10; i++) {
      const { status } = await call(id, { fields: "status,error_message" });
      if (status === "FINISHED") break;
      if (status === "ERROR" || status === "EXPIRED") throw new Error(status);
      await sleep(5000);
    }
  }
  const post = await call(`${USER_ID}/threads_publish`, { creation_id: id }, "POST");
  return post.id;
}

publish({ media_type: "TEXT", text: "Hello from Node 👋" }).then(console.log);

curl -G "https://graph.threads.net/v1.0/MEDIA_ID/insights" \
  -d metric=views,likes,replies,reposts,quotes,shares \
  -d access_token=$THREADS_TOKEN

# Account totals for a date range (Unix timestamps)
curl -G "https://graph.threads.net/v1.0/$THREADS_USER_ID/threads_insights" \
  -d metric=views,likes,replies,reposts,quotes,clicks \
  -d since=1756684800 -d until=1759276800 \
  -d access_token=$THREADS_TOKEN

# Follower demographics (needs 100+ followers)
curl -G "https://graph.threads.net/v1.0/$THREADS_USER_ID/threads_insights" \
  -d metric=follower_demographics -d breakdown=country \
  -d access_token=$THREADS_TOKEN

{
  "data": [
    {
      "name": "views",
      "period": "lifetime",
      "values": [ { "value": 12480 } ],
      "title": "Views",
      "id": "MEDIA_ID/insights/views/lifetime"
    },
    {
      "name": "likes",
      "period": "lifetime",
      "values": [ { "value": 642 } ],
      "title": "Likes",
      "id": "MEDIA_ID/insights/likes/lifetime"
    }
  ]
}