API Documentation

Extract Instagram and TikTok data with simple REST API calls. Profiles, posts, stories, reels, comments, hashtags, locations, and more.

Quick Start

Here's your first API call — fetch any Instagram profile in seconds:

curl -H "Authorization: Bearer gs_your_key" \
  "https://gramscraper.com/api/instagram/v1/user/by/username?username=instagram"

import requests

response = requests.get(
    "https://gramscraper.com/api/instagram/v1/user/by/username",
    params={"username": "instagram"},
    headers={"Authorization": "Bearer gs_your_key"}
)
user = response.json()
print(f"{user['data']['username']} — {user['data']['follower_count']} followers")

const response = await fetch(
  "https://gramscraper.com/api/instagram/v1/user/by/username?username=instagram",
  { headers: { Authorization: "Bearer gs_your_key" } }
);
const { data } = await response.json();
console.log(`${data.username} — ${data.follower_count} followers`);

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer gs_your_api_key

Base URLs

All endpoints are relative to the platform base URL:

Instagram  https://gramscraper.com/api/instagram
TikTok     https://gramscraper.com/api/tiktok

Credits System

Each call costs 0–3 credits and every endpoint below shows its exact price. Direct ID lookups cost 1 credit; endpoints that resolve a username first (e.g. /stories/by/username) cost 2–3 because they make multiple upstream calls; utility converters are free.

Credits never expire. Buy once, use whenever you need them.

Rate Limits

Requests are rate-limited per API key for fair use. If you hit the limit, you'll receive a 429 Too Many Requests response. Back off and retry after a short delay.

Error Codes

All error responses return JSON:

{ "error": "Insufficient credits", "credits_remaining": 0 }

AI assistants (MCP)

GramScraper runs a hosted Model Context Protocol server, so Claude, Cursor, VS Code and other MCP clients can look up public Instagram and TikTok data for you. Tool calls spend credits from your balance at the same prices as the API.

https://gramscraper.com/mcp

Add that URL as a remote MCP server in your client. The client opens a GramScraper page where you log in and approve access. You don’t need to copy an API key.

Settings → Connectors → Add custom connector
Name: GramScraper
URL:  https://gramscraper.com/mcp
Then choose Connect and approve access on gramscraper.com.

claude mcp add --transport http gramscraper https://gramscraper.com/mcp
# then run /mcp inside Claude Code and choose Authenticate

# ~/.cursor/mcp.json
{
  "mcpServers": {
    "gramscraper": { "url": "https://gramscraper.com/mcp" }
  }
}

If your client doesn’t support OAuth, send an API key in a header instead: Authorization: Bearer gs_your_api_key.