{"openapi":"3.0.3","info":{"title":"Airaa Social Data API","version":"1.0.0","description":"Clean REST API for Instagram data — profiles, posts, reels, stories, comments, and more.\n\n**Authentication:** Pass your key in the `X-API-KEY` header on every request. Contact light@airaa.xyz to obtain a key.\n\n**Base URL:** `https://social-api.airaa.xyz`\n\n**For AI agents:** Full machine-readable endpoint index at [`/llms.txt`](/llms.txt).\n\n**Error codes:** `400` bad param · `401` invalid key · `429` quota exceeded · `500` server config · `502` service unavailable · `504` request timed out. All error responses follow the shape `{ error: \"message\" }`."},"x-tagGroups":[{"name":"Instagram","tags":["Instagram User","Instagram Posts/Reels"]}],"servers":[{"url":"https://social.airaa.xyz"}],"tags":[{"name":"Instagram User","description":"Profile, posts, reels, and stories"},{"name":"Instagram Posts/Reels","description":"Media details and comments"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"Your Airaa API key. Include it in every request as the `X-API-KEY` header. Contact the Airaa team to obtain a key."}},"responses":{"BadRequest":{"description":"Missing or invalid query parameter","content":{"application/json":{"schema":{"type":"object"},"example":{"error":"Missing required parameter: username_or_url"}}}},"Unauthorized":{"description":"Missing or invalid `X-API-KEY` header","content":{"application/json":{"schema":{"type":"object"},"example":{"error":"Unauthorized"}}}},"RateLimited":{"description":"Request quota exceeded — contact light@airaa.xyz to upgrade your plan","content":{"application/json":{"schema":{"type":"object"},"example":{"error":"Request quota exceeded — contact light@airaa.xyz to upgrade your plan."}}}},"ServerError":{"description":"Server misconfiguration — API key environment variable not set","content":{"application/json":{"schema":{"type":"object"},"example":{"error":"Server configuration error"}}}},"BadGateway":{"description":"Airaa service temporarily unavailable — please try again","content":{"application/json":{"schema":{"type":"object"},"example":{"error":"Airaa service unavailable — please try again."}}}},"GatewayTimeout":{"description":"Request timed out — please try again","content":{"application/json":{"schema":{"type":"object"},"example":{"error":"Request timed out — please try again."}}}}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/v1/instagram/user/profile":{"get":{"tags":["Instagram User"],"summary":"Get Instagram profile data","description":"Retrieve full Instagram profile including bio, follower count, post count, and verification status.","parameters":[{"in":"query","name":"username_or_url","required":true,"schema":{"type":"string"},"description":"Instagram username or profile URL","example":"instagram"},{"in":"query","name":"data","required":false,"schema":{"type":"string"},"description":"Data scope to return"}],"responses":{"200":{"description":"Profile data","content":{"application/json":{"schema":{"type":"object"},"example":{"username":"instagram","full_name":"Instagram","biography":"Discover what's new on Instagram 🔎✨","is_verified":true,"is_private":false,"follower_count":700883729,"following_count":236,"media_count":8400,"profile_pic_url":"https://scontent.cdninstagram.com/v/t51.82787-19/pic.jpg","bio_links":[{"url":"http://help.instagram.com","title":"","link_type":"external"}],"account_type":3,"is_business":false,"pk":"25025320"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"$ref":"#/components/responses/BadGateway"},"504":{"$ref":"#/components/responses/GatewayTimeout"}}}},"/v1/instagram/user/posts":{"get":{"tags":["Instagram User"],"summary":"Get user posts","description":"Retrieve paginated post feed for a user.","parameters":[{"in":"query","name":"username_or_url","required":true,"schema":{"type":"string"},"example":"instagram"},{"in":"query","name":"cursor","required":false,"schema":{"type":"string"},"description":"Pagination cursor from previous response"}],"responses":{"200":{"description":"Posts list","content":{"application/json":{"schema":{"type":"object"},"example":{"posts":[{"node":{"code":"DXH5RlTDy8N","pk":"3875317901306048269","id":"3875317901306048269_25025320","media_type":2,"like_count":34107,"comment_count":1664,"taken_at":1776194225,"caption":{"text":"Kawaii core, but on a canvas 🎨💫","pk":"18455545261110056"},"original_width":1080,"original_height":1920,"image_versions2":{"candidates":[{"url":"https://scontent.cdninstagram.com/v/...","width":1080,"height":1920}]}}}],"pagination_token":"3865085029567979517_25025320"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"$ref":"#/components/responses/BadGateway"},"504":{"$ref":"#/components/responses/GatewayTimeout"}}}},"/v1/instagram/user/reels":{"get":{"tags":["Instagram User"],"summary":"Get user reels","description":"Retrieve reels with play counts and engagement data.","parameters":[{"in":"query","name":"username_or_url","required":true,"schema":{"type":"string"},"example":"instagram"},{"in":"query","name":"cursor","required":false,"schema":{"type":"string"},"description":"Pagination cursor from previous response"}],"responses":{"200":{"description":"Reels list","content":{"application/json":{"schema":{"type":"object"},"example":{"reels":[{"node":{"media":{"pk":"3875317901306048269","id":"3875317901306048269_25025320","code":"DXH5RlTDy8N","media_type":2,"play_count":27827344,"like_count":34186,"comment_count":1671,"product_type":"clips","image_versions2":{"candidates":[{"url":"https://scontent.cdninstagram.com/v/...","width":1215,"height":2160}]},"user":{"pk":"25025320","id":"25025320"}}}}],"pagination_token":"QVFDUktROXg2Rk5oTkFtd2MtWTAxeE..."}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"$ref":"#/components/responses/BadGateway"},"504":{"$ref":"#/components/responses/GatewayTimeout"}}}},"/v1/instagram/user/stories":{"get":{"tags":["Instagram User"],"summary":"Get user stories","parameters":[{"in":"query","name":"username_or_url","required":true,"schema":{"type":"string"},"example":"instagram"}],"responses":{"200":{"description":"Active stories","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}},"example":[{"id":"3875322197246433847_25025320","pk":"3875322197246433847","code":"DXH6QGND1o3","media_type":2,"taken_at":1776194408,"expiring_at":1776280808,"has_audio":true,"video_duration":21.5,"original_width":1080,"original_height":1920,"image_versions2":{"candidates":[{"url":"https://scontent.cdninstagram.com/v/...","width":640,"height":1136}]},"video_versions":[{"url":"https://scontent.cdninstagram.com/o1/v/...","width":720,"height":1280}]}]}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"$ref":"#/components/responses/BadGateway"},"504":{"$ref":"#/components/responses/GatewayTimeout"}}}},"/v1/instagram/posts/details":{"get":{"tags":["Instagram Posts/Reels"],"summary":"Get post or reel data","description":"Retrieve full media details including like count, comment count, play count, caption, and author info.","parameters":[{"in":"query","name":"media_code_or_url","required":true,"schema":{"type":"string"},"description":"Media code (e.g. DJmAsFEPfNV) or post/reel URL"}],"responses":{"200":{"description":"Media data","content":{"application/json":{"schema":{"type":"object"},"example":{"id":"3875317901306048269","shortcode":"DXH5RlTDy8N","is_video":true,"video_play_count":27782799,"video_view_count":3641522,"video_duration":21.5,"video_url":"https://scontent.cdninstagram.com/o1/v/...","display_url":"https://scontent.cdninstagram.com/v/t51.82787-15/...","taken_at_timestamp":1776194225,"edge_media_preview_like":{"count":34131,"edges":[]},"edge_media_to_parent_comment":{"count":1667},"edge_media_to_caption":{"edges":[{"node":{"text":"Kawaii core, but on a canvas 🎨💫","created_at":"1776194217","id":"18455545261110056"}}]},"owner":{"id":"25025320","username":"instagram","full_name":"Instagram","is_verified":true,"profile_pic_url":"https://scontent.cdninstagram.com/v/profile.jpg"},"edge_media_to_tagged_user":{"edges":[{"node":{"user":{"username":"mada.exe","id":"6681152293","is_verified":false}}}]},"location":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"$ref":"#/components/responses/BadGateway"},"504":{"$ref":"#/components/responses/GatewayTimeout"}}}},"/v1/instagram/posts/comments":{"get":{"tags":["Instagram Posts/Reels"],"summary":"Get post comments","parameters":[{"in":"query","name":"media_id","required":true,"schema":{"type":"string"},"description":"Media ID (numeric)"},{"in":"query","name":"sort_order","required":false,"schema":{"type":"string"},"description":"Sort order for comments"},{"in":"query","name":"cursor","required":false,"schema":{"type":"string"},"description":"Pagination cursor from previous response"}],"responses":{"200":{"description":"Comments","content":{"application/json":{"schema":{"type":"object"},"example":{"comments":[{"pk":"18520748122076499","text":"😍😍😍","created_at":1776201448,"comment_like_count":26,"child_comment_count":1,"user":{"pk":"9378450129","id":"9378450129","username":"kentsuneda","is_verified":true,"profile_pic_url":"https://scontent.cdninstagram.com/v/pic.jpg"}}],"pagination_token":"{\"cached_comments_cursor\":\"17973477114008520\",...}"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"$ref":"#/components/responses/BadGateway"},"504":{"$ref":"#/components/responses/GatewayTimeout"}}}}}}