# Airaa Social Data API
> REST API for Instagram data — profiles, posts, reels, stories, and more. Powered by Airaa.

Base URL: https://social-api.airaa.xyz
Authentication: X-API-KEY header (contact light@airaa.xyz to obtain a key)
OpenAPI spec: https://social-api.airaa.xyz/openapi.json
Interactive docs: https://social-api.airaa.xyz/docs

## Authentication

Every request must include the `X-API-KEY` header:

```
curl -H "X-API-KEY: YOUR_KEY" "https://social-api.airaa.xyz/v1/instagram/user/profile?username_or_url=instagram"
```

Error responses follow this shape: `{ "error": "message" }` or `{ "message": "message" }`

HTTP error codes:
- 400 — Missing or invalid query parameter
- 401 — Missing or invalid X-API-KEY
- 429 — Request quota exceeded (contact light@airaa.xyz to upgrade)
- 500 — Server misconfiguration
- 502 — Airaa service unavailable
- 504 — Request timed out

---

## Instagram Endpoints

GET /v1/instagram/user/profile
  Params: username_or_url (required), data (optional)
  Returns: username, full_name, is_verified, is_private, biography, follower_count, following_count, media_count, profile_pic_url, bio_links, account_type, is_business, pk

GET /v1/instagram/user/posts
  Params: username_or_url (required), cursor (optional — pass pagination_token from previous response)
  Returns: { posts: [{ node: { code, pk, id, media_type, like_count, comment_count, taken_at, caption: { text }, image_versions2, video_versions, original_width, original_height } }], pagination_token }

GET /v1/instagram/user/reels
  Params: username_or_url (required), cursor (optional — pass pagination_token from previous response)
  Returns: { reels: [{ node: { media: { pk, code, media_type, play_count, like_count, comment_count, product_type, image_versions2, user } } }], pagination_token }

GET /v1/instagram/user/stories
  Params: username_or_url (required)
  Returns: Array of story items with id, pk, code, media_type, taken_at, expiring_at, has_audio, video_duration, image_versions2, video_versions

GET /v1/instagram/posts/details
  Params: media_code_or_url (required — media code or post/reel URL)
  Returns: { shortcode, is_video, video_play_count, video_view_count, video_duration, video_url, display_url, taken_at_timestamp, edge_media_preview_like: { count }, edge_media_to_parent_comment: { count }, edge_media_to_caption: { edges: [{ node: { text } }] }, owner: { id, username, full_name, is_verified }, edge_media_to_tagged_user, location }

GET /v1/instagram/posts/comments
  Params: media_id (required), sort_order (optional), cursor (optional — pass pagination_token from previous response)
  Returns: { comments: [{ pk, text, created_at, comment_like_count, child_comment_count, user: { pk, username, is_verified, profile_pic_url } }], pagination_token }