# posts Post reads — single and batch. # Read one post by URL, or many posts by identifier list `GET /posts` Two mutually exclusive forms — supplying both `url` and `ids` is a 400. `url` is a single read: returns the post document wrapped as `{ data: }` (200), a `FetchingResponse` (202), or an `error` envelope (404). `ids` is the batch form: always 200, the three-bucket envelope. A post read can take longer than an account read — it may walk the author's recent media. Requires `posts:read`. Full operation definition — parameters, request/response schemas, and examples, fully dereferenced against the OpenAPI document: ```json { "operationId": "getPosts", "tags": [ "posts" ], "summary": "Read one post by URL, or many posts by identifier list", "description": "Two mutually exclusive forms — supplying both `url` and `ids` is a 400. `url` is a single read: returns the post document wrapped as `{ data: }` (200), a `FetchingResponse` (202), or an `error` envelope (404). `ids` is the batch form: always 200, the three-bucket envelope. A post read can take longer than an account read — it may walk the author's recent media. Requires `posts:read`.", "x-required-scope": "posts:read", "parameters": [ { "name": "url", "in": "query", "required": false, "description": "The post's URL — the single-read identifier (a post identifier is a URL, unlike a creator's clean network/handle segments). Exactly one of `url` or `ids` must be supplied.", "schema": { "type": "string" }, "examples": { "somehandle": { "value": "https://www.instagram.com/p/DEF456/" } } }, { "name": "ids", "in": "query", "required": false, "description": "Comma-separated identifiers, 1–100 — selects the batch form. Same identifier grammar as `GET /creators?ids=`. Exactly one of `url` or `ids` must be supplied.", "schema": { "type": "string" } }, { "name": "network", "in": "query", "required": false, "description": "Default network for BARE identifiers in `ids` (defaults to `instagram`). Never a filter — a qualified (`instagram:handle`) or URL identifier carries its own network.", "schema": { "type": "string", "default": "instagram" } }, { "name": "include", "in": "query", "required": false, "description": "ASP-1144 — comma-separated AI-enrichment fields to add to the returned `analysis` object (both the `url` and `ids` forms of `GET /posts`; not supported on `POST /posts/batch`). Each named field appears under `analysis` in the response ONLY when requested — an unrequested field's key is entirely absent, never null-padded. Supported values: `narration`, `transcript`, `overlayText`, `languages`, `aestheticTags`, `brandSafety`, `commercialAnalysis`, `emotionalAnalysis`, `productionAnalysis`, `vibeAnalysis`, `subjectAnalysis`, `commentSentimentLabel`, `commentSentimentScore`, `commentSentimentSummary`, `commentSentimentRationale`, `commentSentimentThemes`, `commentSentimentBreakdown`, `commentSentimentTotalCommentCount`, `commentSentimentRelevantCommentCount`. An unrecognized value is a 400.", "schema": { "type": "string" } }, { "name": "asOrg", "in": "query", "required": false, "description": "Names a target Organization to act on, when it differs from your credential's own organization — for a delegated agency/partner relationship.", "schema": { "type": "string" } }, { "name": "asProfile", "in": "query", "required": false, "description": "Attribution only — associates this read's discovery/refresh work with one of your Profiles, resolved within your organization.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`SinglePostResponse` (`{ data: }`) for the `url` form; `PostsBatchResponse` (the three-bucket envelope, `Retry-After` present iff `fetching` is non-empty) for the `ids` form.", "headers": { "x-request-id": { "description": "On every response, success or failure. Quote it when contacting support — it's the fastest way for Aspire to find exactly your request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Present iff `fetching` is non-empty — delta-seconds until those entries are worth re-submitting (every fetching entry in one response shares the same instant).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "network": { "type": "string", "const": "instagram", "description": "The social network this post is on." }, "externalId": { "description": "The post's network-native identifier.", "type": [ "string", "null" ] }, "url": { "description": "The post's public permalink.", "type": [ "string", "null" ] }, "postedAt": { "description": "ISO 8601 timestamp of when the post was published.", "type": [ "string", "null" ] }, "text": { "description": "The post's caption text.", "type": [ "string", "null" ] }, "mediaKind": { "description": "The post's media type — `video`, `image`, or `carousel`.", "enum": [ "video", "image", "carousel", null ], "type": [ "string", "null" ] }, "likeCount": { "description": "Total like count.", "type": [ "number", "null" ] }, "commentCount": { "description": "Total comment count.", "type": [ "number", "null" ] }, "viewCount": { "description": "Total view count.", "type": [ "number", "null" ] }, "shareCount": { "description": "Total share count.", "type": [ "number", "null" ] }, "saveCount": { "description": "Total save count.", "type": [ "number", "null" ] }, "author": { "type": "object", "properties": { "accountId": { "description": "The post author's network-native account identifier.", "type": [ "string", "null" ] }, "username": { "description": "The post author's @handle.", "type": [ "string", "null" ] }, "followersCount": { "description": "Total number of followers the post author has.", "type": [ "number", "null" ] }, "verified": { "description": "Whether the post author's identity is verified on the network.", "type": [ "boolean", "null" ] }, "country": { "description": "The post author's country.", "type": [ "string", "null" ] } }, "required": [ "accountId", "username", "followersCount", "verified", "country" ] }, "instagram": { "type": "object", "properties": { "igMediaId": { "description": "Numeric media id for this post.", "type": [ "string", "null" ] }, "igUserId": { "description": "The Instagram-scoped user id of the post's author.", "type": [ "string", "null" ] }, "authorUsername": { "description": "The post author's @handle (core `author.username` is canonical).", "type": [ "string", "null" ] }, "shortcode": { "description": "Short alphanumeric code for this post, as used in its permalink.", "type": [ "string", "null" ] }, "mediaType": { "description": "The post's raw media-type value (core `mediaKind` is the mapped video/image/carousel value).", "type": [ "string", "null" ] }, "mediaAudioType": { "description": "The type of audio used in the media. Can be `MUSIC` or `ORIGINAL_SOUND`.", "type": [ "string", "null" ] }, "mediaProductType": { "description": "Product-type classification for this media (e.g. feed post, reel, story).", "type": [ "string", "null" ] }, "isSharedToFeed": { "description": "For Reels only. When `true`, the reel can appear in both the Feed and Reels tabs. When `false`, the reel can only appear in the Reels tab.", "type": [ "boolean", "null" ] }, "permalink": { "description": "The post's public URL — same value as core `url`.", "type": [ "string", "null" ] }, "caption": { "description": "The post's caption text — same value as core `text`.", "type": [ "string", "null" ] }, "organicLikeCount": { "description": "Likes attributable to organic (non-paid) delivery only.", "type": [ "number", "null" ] }, "totalLikeCount": { "description": "Total likes across organic and paid delivery — same value as core `likeCount`.", "type": [ "number", "null" ] }, "organicCommentCount": { "description": "Comments attributable to organic delivery only.", "type": [ "number", "null" ] }, "totalCommentCount": { "description": "Total comments across organic and paid delivery — same value as core `commentCount`.", "type": [ "number", "null" ] }, "organicViewCount": { "description": "Views attributable to organic delivery only.", "type": [ "number", "null" ] }, "totalViewCount": { "description": "Total views across organic and paid delivery — same value as core `viewCount`.", "type": [ "number", "null" ] }, "organicRepostCount": { "description": "Reposts (reshares by other accounts) attributable to organic delivery.", "type": [ "number", "null" ] }, "organicSaveCount": { "description": "Saves attributable to organic delivery only.", "type": [ "number", "null" ] }, "organicShareCount": { "description": "Shares attributable to organic delivery only.", "type": [ "number", "null" ] }, "organicReach": { "description": "Distinct accounts that organically saw this post.", "type": [ "number", "null" ] }, "organicTotalInteractions": { "description": "Sum of organic likes, comments, saves, and shares on this post.", "type": [ "number", "null" ] }, "organicFollows": { "description": "Accounts that started following the creator as a direct result of this post (organic only).", "type": [ "number", "null" ] }, "organicProfileVisits": { "description": "Visits to the creator's profile attributable to this post (organic only).", "type": [ "number", "null" ] }, "organicProfileActivity": { "description": "The number of actions people took on the creator's profile after visiting it from this post — bio link clicks, or taps on the call, direction, email, or text buttons (organic only, feed and story posts).", "type": [ "number", "null" ] }, "organicFacebookViews": { "description": "Views of this post's cross-posted copy on Facebook (organic only).", "type": [ "number", "null" ] }, "organicCrosspostedViews": { "description": "Total number of times this post was played, aggregated across Instagram and Facebook (organic only, Reels only).", "type": [ "number", "null" ] }, "organicIgReelsAvgWatchTime": { "description": "Average watch time per view, for Reels (organic only).", "type": [ "number", "null" ] }, "organicIgReelsVideoViewTotalTime": { "description": "Total cumulative watch time across all views, for Reels (organic only).", "type": [ "number", "null" ] }, "organicLinkClicks": { "description": "Clicks on a link included in this post (e.g. a Story link sticker), organic only.", "type": [ "number", "null" ] }, "organicNavigation": { "description": "Total navigation actions taken while viewing this post — the sum of exits, taps forward, taps back, and advances to the next story (organic only, story posts).", "type": [ "number", "null" ] }, "organicReplies": { "description": "Replies sent in response to this post (e.g. Story replies), organic only.", "type": [ "number", "null" ] }, "organicExits": { "description": "Instances of a viewer exiting out of this post entirely (e.g. leaving a Story), organic only.", "type": [ "number", "null" ] }, "organicTapsForward": { "description": "Taps to advance past this post (e.g. tapping forward through a Story), organic only.", "type": [ "number", "null" ] }, "organicTapsBack": { "description": "Taps to go back and re-view this post (e.g. tapping back through a Story), organic only.", "type": [ "number", "null" ] }, "hashtags": { "description": "Hashtags extracted from this post's caption.", "type": "array", "items": { "type": "string" } }, "mentions": { "description": "Accounts mentioned in this post — see `PostMention` fields above.", "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string", "description": "The @handle of the mentioned account." }, "type": { "type": "string", "enum": [ "TAG", "CAPTION", "STORY", "COLLAB", "PAID_PARTNERSHIP" ], "description": "How the mention occurred — `TAG`, `CAPTION`, `STORY`, `COLLAB`, or `PAID_PARTNERSHIP`." }, "resolved": { "type": "boolean", "description": "Whether the mentioned username has been resolved to a known account in our system." }, "inviteStatus": { "type": [ "string", "null" ] } }, "required": [ "username", "type", "resolved", "inviteStatus" ] } } }, "required": [ "igMediaId", "igUserId", "authorUsername", "shortcode", "mediaType", "mediaAudioType", "mediaProductType", "isSharedToFeed", "permalink", "caption", "organicLikeCount", "totalLikeCount", "organicCommentCount", "totalCommentCount", "organicViewCount", "totalViewCount", "organicRepostCount", "organicSaveCount", "organicShareCount", "organicReach", "organicTotalInteractions", "organicFollows", "organicProfileVisits", "organicProfileActivity", "organicFacebookViews", "organicCrosspostedViews", "organicIgReelsAvgWatchTime", "organicIgReelsVideoViewTotalTime", "organicLinkClicks", "organicNavigation", "organicReplies", "organicExits", "organicTapsForward", "organicTapsBack", "hashtags", "mentions" ] }, "updatedAt": { "description": "ISO 8601 timestamp of when this post's current snapshot was produced — how fresh this document is.", "type": [ "string", "null" ] }, "analysis": { "type": "object", "properties": { "narration": { "description": "AI-generated (Gemini multimodal) narration of the video/audio content.", "type": [ "string", "null" ] }, "transcript": { "description": "AI-generated (Gemini multimodal) transcript of spoken audio.", "type": [ "string", "null" ] }, "overlayText": { "description": "AI-detected on-screen text overlays, in detection order.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "languages": { "description": "AI-detected spoken/on-screen languages, as free-text labels.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "aestheticTags": { "description": "AI-generated free-text aesthetic/style tags.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "brandSafety": { "description": "AI-judged brand-safety risk per GARM category — a judged VERDICT, not raw enrichment. `null` if not yet judged, or if the judged shape no longer matches the current GARM taxonomy.", "properties": { "adult_content": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "arms_ammunition": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "crime_harmful_acts": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "death_injury": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "online_piracy": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "hate_speech": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "obscenity_profanity": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "illegal_drugs": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "spam_harmful": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "terrorism": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "debated_sensitive_social_issue": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "misinformation": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] } }, "required": [ "adult_content", "arms_ammunition", "crime_harmful_acts", "death_injury", "online_piracy", "hate_speech", "obscenity_profanity", "illegal_drugs", "spam_harmful", "terrorism", "debated_sensitive_social_issue", "misinformation" ], "type": [ "object", "null" ] }, "commercialAnalysis": { "description": "AI-detected commercial signals — featured products/brands, calls to action, promo codes, and a 1-5 promotional-intent score.", "properties": { "featuredProducts": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "featuredBrands": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "callToActions": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "promoCodes": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "promotionalIntent": { "type": [ "number", "null" ] } }, "required": [ "featuredProducts", "featuredBrands", "callToActions", "promoCodes", "promotionalIntent" ], "type": [ "object", "null" ] }, "emotionalAnalysis": { "description": "AI-judged primary emotion and tone.", "properties": { "primaryEmotion": { "type": [ "string", "null" ] }, "tone": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "primaryEmotion", "tone" ], "type": [ "object", "null" ] }, "productionAnalysis": { "description": "AI-judged production quality and technique signals.", "properties": { "productionQuality": { "type": [ "number", "null" ] }, "cameraTechniques": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "audioStyle": { "type": [ "string", "null" ] }, "lightingStyle": { "type": [ "string", "null" ] } }, "required": [ "productionQuality", "cameraTechniques", "audioStyle", "lightingStyle" ], "type": [ "object", "null" ] }, "vibeAnalysis": { "description": "Opaque AI-generated vibe classification — shape is not fixed; treat as untyped JSON." }, "subjectAnalysis": { "description": "Opaque AI-generated subject classification — shape is not fixed; treat as untyped JSON." }, "commentSentimentLabel": { "description": "AI-judged overall comment sentiment label.", "enum": [ "positive", "neutral", "negative", "mixed", null ], "type": [ "string", "null" ] }, "commentSentimentScore": { "description": "AI-judged overall comment sentiment score.", "type": [ "number", "null" ] }, "commentSentimentSummary": { "description": "AI-generated free-text summary of comment sentiment.", "type": [ "string", "null" ] }, "commentSentimentRationale": { "description": "AI-generated free-text rationale for the sentiment judgment.", "type": [ "string", "null" ] }, "commentSentimentThemes": { "description": "AI-generated free-text comment themes.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "commentSentimentBreakdown": { "description": "AI-judged comment sentiment split into positive/neutral/negative buckets, each a count and percentage of comments analyzed.", "properties": { "positive": { "type": "object", "properties": { "count": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "count", "percentage" ] }, "neutral": { "type": "object", "properties": { "count": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "count", "percentage" ] }, "negative": { "type": "object", "properties": { "count": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "count", "percentage" ] } }, "required": [ "positive", "neutral", "negative" ], "type": [ "object", "null" ] }, "commentSentimentTotalCommentCount": { "description": "Total comments considered in the sentiment judgment.", "type": [ "number", "null" ] }, "commentSentimentRelevantCommentCount": { "description": "Comments judged relevant to the sentiment analysis — a subset of the total.", "type": [ "number", "null" ] } }, "description": "AI-generated (Gemini multimodal) enrichment preview — opt-in via `?include=` (see the `include` query parameter), one key per requested field. Coverage and shape may change without notice." } }, "required": [ "network", "externalId", "url", "postedAt", "text", "mediaKind", "likeCount", "commentCount", "viewCount", "shareCount", "saveCount", "author", "instagram", "updatedAt" ] } }, "required": [ "data" ], "description": "Returned with HTTP 200: the document we hold, wrapped the same way a batch read's `data` bucket wraps each entry." }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string", "const": "instagram", "description": "The social network this post is on." }, "externalId": { "description": "The post's network-native identifier.", "type": [ "string", "null" ] }, "url": { "description": "The post's public permalink.", "type": [ "string", "null" ] }, "postedAt": { "description": "ISO 8601 timestamp of when the post was published.", "type": [ "string", "null" ] }, "text": { "description": "The post's caption text.", "type": [ "string", "null" ] }, "mediaKind": { "description": "The post's media type — `video`, `image`, or `carousel`.", "enum": [ "video", "image", "carousel", null ], "type": [ "string", "null" ] }, "likeCount": { "description": "Total like count.", "type": [ "number", "null" ] }, "commentCount": { "description": "Total comment count.", "type": [ "number", "null" ] }, "viewCount": { "description": "Total view count.", "type": [ "number", "null" ] }, "shareCount": { "description": "Total share count.", "type": [ "number", "null" ] }, "saveCount": { "description": "Total save count.", "type": [ "number", "null" ] }, "author": { "type": "object", "properties": { "accountId": { "description": "The post author's network-native account identifier.", "type": [ "string", "null" ] }, "username": { "description": "The post author's @handle.", "type": [ "string", "null" ] }, "followersCount": { "description": "Total number of followers the post author has.", "type": [ "number", "null" ] }, "verified": { "description": "Whether the post author's identity is verified on the network.", "type": [ "boolean", "null" ] }, "country": { "description": "The post author's country.", "type": [ "string", "null" ] } }, "required": [ "accountId", "username", "followersCount", "verified", "country" ] }, "instagram": { "type": "object", "properties": { "igMediaId": { "description": "Numeric media id for this post.", "type": [ "string", "null" ] }, "igUserId": { "description": "The Instagram-scoped user id of the post's author.", "type": [ "string", "null" ] }, "authorUsername": { "description": "The post author's @handle (core `author.username` is canonical).", "type": [ "string", "null" ] }, "shortcode": { "description": "Short alphanumeric code for this post, as used in its permalink.", "type": [ "string", "null" ] }, "mediaType": { "description": "The post's raw media-type value (core `mediaKind` is the mapped video/image/carousel value).", "type": [ "string", "null" ] }, "mediaAudioType": { "description": "The type of audio used in the media. Can be `MUSIC` or `ORIGINAL_SOUND`.", "type": [ "string", "null" ] }, "mediaProductType": { "description": "Product-type classification for this media (e.g. feed post, reel, story).", "type": [ "string", "null" ] }, "isSharedToFeed": { "description": "For Reels only. When `true`, the reel can appear in both the Feed and Reels tabs. When `false`, the reel can only appear in the Reels tab.", "type": [ "boolean", "null" ] }, "permalink": { "description": "The post's public URL — same value as core `url`.", "type": [ "string", "null" ] }, "caption": { "description": "The post's caption text — same value as core `text`.", "type": [ "string", "null" ] }, "organicLikeCount": { "description": "Likes attributable to organic (non-paid) delivery only.", "type": [ "number", "null" ] }, "totalLikeCount": { "description": "Total likes across organic and paid delivery — same value as core `likeCount`.", "type": [ "number", "null" ] }, "organicCommentCount": { "description": "Comments attributable to organic delivery only.", "type": [ "number", "null" ] }, "totalCommentCount": { "description": "Total comments across organic and paid delivery — same value as core `commentCount`.", "type": [ "number", "null" ] }, "organicViewCount": { "description": "Views attributable to organic delivery only.", "type": [ "number", "null" ] }, "totalViewCount": { "description": "Total views across organic and paid delivery — same value as core `viewCount`.", "type": [ "number", "null" ] }, "organicRepostCount": { "description": "Reposts (reshares by other accounts) attributable to organic delivery.", "type": [ "number", "null" ] }, "organicSaveCount": { "description": "Saves attributable to organic delivery only.", "type": [ "number", "null" ] }, "organicShareCount": { "description": "Shares attributable to organic delivery only.", "type": [ "number", "null" ] }, "organicReach": { "description": "Distinct accounts that organically saw this post.", "type": [ "number", "null" ] }, "organicTotalInteractions": { "description": "Sum of organic likes, comments, saves, and shares on this post.", "type": [ "number", "null" ] }, "organicFollows": { "description": "Accounts that started following the creator as a direct result of this post (organic only).", "type": [ "number", "null" ] }, "organicProfileVisits": { "description": "Visits to the creator's profile attributable to this post (organic only).", "type": [ "number", "null" ] }, "organicProfileActivity": { "description": "The number of actions people took on the creator's profile after visiting it from this post — bio link clicks, or taps on the call, direction, email, or text buttons (organic only, feed and story posts).", "type": [ "number", "null" ] }, "organicFacebookViews": { "description": "Views of this post's cross-posted copy on Facebook (organic only).", "type": [ "number", "null" ] }, "organicCrosspostedViews": { "description": "Total number of times this post was played, aggregated across Instagram and Facebook (organic only, Reels only).", "type": [ "number", "null" ] }, "organicIgReelsAvgWatchTime": { "description": "Average watch time per view, for Reels (organic only).", "type": [ "number", "null" ] }, "organicIgReelsVideoViewTotalTime": { "description": "Total cumulative watch time across all views, for Reels (organic only).", "type": [ "number", "null" ] }, "organicLinkClicks": { "description": "Clicks on a link included in this post (e.g. a Story link sticker), organic only.", "type": [ "number", "null" ] }, "organicNavigation": { "description": "Total navigation actions taken while viewing this post — the sum of exits, taps forward, taps back, and advances to the next story (organic only, story posts).", "type": [ "number", "null" ] }, "organicReplies": { "description": "Replies sent in response to this post (e.g. Story replies), organic only.", "type": [ "number", "null" ] }, "organicExits": { "description": "Instances of a viewer exiting out of this post entirely (e.g. leaving a Story), organic only.", "type": [ "number", "null" ] }, "organicTapsForward": { "description": "Taps to advance past this post (e.g. tapping forward through a Story), organic only.", "type": [ "number", "null" ] }, "organicTapsBack": { "description": "Taps to go back and re-view this post (e.g. tapping back through a Story), organic only.", "type": [ "number", "null" ] }, "hashtags": { "description": "Hashtags extracted from this post's caption.", "type": "array", "items": { "type": "string" } }, "mentions": { "description": "Accounts mentioned in this post — see `PostMention` fields above.", "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string", "description": "The @handle of the mentioned account." }, "type": { "type": "string", "enum": [ "TAG", "CAPTION", "STORY", "COLLAB", "PAID_PARTNERSHIP" ], "description": "How the mention occurred — `TAG`, `CAPTION`, `STORY`, `COLLAB`, or `PAID_PARTNERSHIP`." }, "resolved": { "type": "boolean", "description": "Whether the mentioned username has been resolved to a known account in our system." }, "inviteStatus": { "type": [ "string", "null" ] } }, "required": [ "username", "type", "resolved", "inviteStatus" ] } } }, "required": [ "igMediaId", "igUserId", "authorUsername", "shortcode", "mediaType", "mediaAudioType", "mediaProductType", "isSharedToFeed", "permalink", "caption", "organicLikeCount", "totalLikeCount", "organicCommentCount", "totalCommentCount", "organicViewCount", "totalViewCount", "organicRepostCount", "organicSaveCount", "organicShareCount", "organicReach", "organicTotalInteractions", "organicFollows", "organicProfileVisits", "organicProfileActivity", "organicFacebookViews", "organicCrosspostedViews", "organicIgReelsAvgWatchTime", "organicIgReelsVideoViewTotalTime", "organicLinkClicks", "organicNavigation", "organicReplies", "organicExits", "organicTapsForward", "organicTapsBack", "hashtags", "mentions" ] }, "updatedAt": { "description": "ISO 8601 timestamp of when this post's current snapshot was produced — how fresh this document is.", "type": [ "string", "null" ] }, "analysis": { "type": "object", "properties": { "narration": { "description": "AI-generated (Gemini multimodal) narration of the video/audio content.", "type": [ "string", "null" ] }, "transcript": { "description": "AI-generated (Gemini multimodal) transcript of spoken audio.", "type": [ "string", "null" ] }, "overlayText": { "description": "AI-detected on-screen text overlays, in detection order.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "languages": { "description": "AI-detected spoken/on-screen languages, as free-text labels.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "aestheticTags": { "description": "AI-generated free-text aesthetic/style tags.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "brandSafety": { "description": "AI-judged brand-safety risk per GARM category — a judged VERDICT, not raw enrichment. `null` if not yet judged, or if the judged shape no longer matches the current GARM taxonomy.", "properties": { "adult_content": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "arms_ammunition": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "crime_harmful_acts": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "death_injury": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "online_piracy": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "hate_speech": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "obscenity_profanity": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "illegal_drugs": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "spam_harmful": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "terrorism": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "debated_sensitive_social_issue": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "misinformation": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] } }, "required": [ "adult_content", "arms_ammunition", "crime_harmful_acts", "death_injury", "online_piracy", "hate_speech", "obscenity_profanity", "illegal_drugs", "spam_harmful", "terrorism", "debated_sensitive_social_issue", "misinformation" ], "type": [ "object", "null" ] }, "commercialAnalysis": { "description": "AI-detected commercial signals — featured products/brands, calls to action, promo codes, and a 1-5 promotional-intent score.", "properties": { "featuredProducts": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "featuredBrands": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "callToActions": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "promoCodes": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "promotionalIntent": { "type": [ "number", "null" ] } }, "required": [ "featuredProducts", "featuredBrands", "callToActions", "promoCodes", "promotionalIntent" ], "type": [ "object", "null" ] }, "emotionalAnalysis": { "description": "AI-judged primary emotion and tone.", "properties": { "primaryEmotion": { "type": [ "string", "null" ] }, "tone": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "primaryEmotion", "tone" ], "type": [ "object", "null" ] }, "productionAnalysis": { "description": "AI-judged production quality and technique signals.", "properties": { "productionQuality": { "type": [ "number", "null" ] }, "cameraTechniques": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "audioStyle": { "type": [ "string", "null" ] }, "lightingStyle": { "type": [ "string", "null" ] } }, "required": [ "productionQuality", "cameraTechniques", "audioStyle", "lightingStyle" ], "type": [ "object", "null" ] }, "vibeAnalysis": { "description": "Opaque AI-generated vibe classification — shape is not fixed; treat as untyped JSON." }, "subjectAnalysis": { "description": "Opaque AI-generated subject classification — shape is not fixed; treat as untyped JSON." }, "commentSentimentLabel": { "description": "AI-judged overall comment sentiment label.", "enum": [ "positive", "neutral", "negative", "mixed", null ], "type": [ "string", "null" ] }, "commentSentimentScore": { "description": "AI-judged overall comment sentiment score.", "type": [ "number", "null" ] }, "commentSentimentSummary": { "description": "AI-generated free-text summary of comment sentiment.", "type": [ "string", "null" ] }, "commentSentimentRationale": { "description": "AI-generated free-text rationale for the sentiment judgment.", "type": [ "string", "null" ] }, "commentSentimentThemes": { "description": "AI-generated free-text comment themes.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "commentSentimentBreakdown": { "description": "AI-judged comment sentiment split into positive/neutral/negative buckets, each a count and percentage of comments analyzed.", "properties": { "positive": { "type": "object", "properties": { "count": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "count", "percentage" ] }, "neutral": { "type": "object", "properties": { "count": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "count", "percentage" ] }, "negative": { "type": "object", "properties": { "count": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "count", "percentage" ] } }, "required": [ "positive", "neutral", "negative" ], "type": [ "object", "null" ] }, "commentSentimentTotalCommentCount": { "description": "Total comments considered in the sentiment judgment.", "type": [ "number", "null" ] }, "commentSentimentRelevantCommentCount": { "description": "Comments judged relevant to the sentiment analysis — a subset of the total.", "type": [ "number", "null" ] } }, "description": "AI-generated (Gemini multimodal) enrichment preview — opt-in via `?include=` (see the `include` query parameter), one key per requested field. Coverage and shape may change without notice." } }, "required": [ "network", "externalId", "url", "postedAt", "text", "mediaKind", "likeCount", "commentCount", "viewCount", "shareCount", "saveCount", "author", "instagram", "updatedAt" ] }, "description": "Documents we hold — same shape as the single read's 200 body." }, "fetching": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The identifier exactly as submitted." }, "retryAfter": { "type": "string", "description": "ISO 8601 instant — every fetching entry in one response shares the same instant, and the response's Retry-After header (present iff this bucket is non-empty) is its delta-seconds twin." } }, "required": [ "id", "retryAfter" ], "description": "A submitted identifier we don't hold yet — this batch read started (or joined) discovery for it. Re-submit it after Retry-After." } }, "unavailable": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The identifier exactly as submitted." }, "reason": { "type": "string", "description": "Machine-readable, open vocabulary (additions are non-breaking). `outside-recent-media-window` and `author-unresolved` occur on posts only. `internal-error` means the failure was on our side — `retryable` is true." }, "retryable": { "description": "Present, and always true, when the failure was on our side rather than a fact about the entity — retry after a few minutes. Absent means terminal: stop retrying.", "type": "boolean", "const": true } }, "required": [ "id", "reason" ], "description": "A submitted identifier that resolved to 'not obtainable'. Check reason (and retryable) — most values mean stop retrying." } } }, "required": [ "data", "fetching", "unavailable" ], "description": "The three-bucket batch envelope, returned with HTTP 200 always — per-item outcomes are buckets, never per-item HTTP statuses. Every submitted identifier appears in exactly one bucket. The response's Retry-After header is present iff `fetching` is non-empty." } ] }, "examples": { "somehandle": { "value": { "data": { "network": "instagram", "externalId": "media-def456", "url": "https://www.instagram.com/p/DEF456/", "postedAt": "2026-08-01T00:00:00.000Z", "text": "a conformance caption", "mediaKind": "image", "likeCount": 12, "commentCount": 1, "viewCount": 110, "shareCount": 3, "saveCount": 2, "author": { "accountId": "ig-def456", "username": "somehandle", "followersCount": 1000, "verified": true, "country": "US" }, "instagram": {}, "updatedAt": "2026-08-01T00:00:00.000Z" } } } } } } }, "202": { "description": "We don't hold this entity yet — THIS request just started (or joined) the work to get it. Wait `Retry-After` seconds and re-read the same URL: the read is the poll, there is no job resource. A read here is not free of side effects — reading an entity we don't hold triggers discovery, and reading a stale one triggers a refresh. (`url` form only — the `ids` form expresses in-flight discovery as the `fetching` bucket inside a 200.)", "headers": { "x-request-id": { "description": "On every response, success or failure. Quote it when contacting support — it's the fastest way for Aspire to find exactly your request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Delta-seconds (RFC 9110 §10.2.3), always ≥ 1. The server controls the backoff — polling faster than this burns rate limit and gets the data no sooner.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "fetching": { "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The identifier exactly as submitted." }, "retryAfter": { "type": "string", "description": "ISO 8601 instant — every fetching entry in one response shares the same instant, and the response's Retry-After header (present iff this bucket is non-empty) is its delta-seconds twin." } }, "required": [ "id", "retryAfter" ], "description": "A submitted identifier we don't hold yet — this batch read started (or joined) discovery for it. Re-submit it after Retry-After." } } }, "required": [ "fetching" ], "description": "Returned with HTTP 202: the entity isn't held yet and THIS request just started (or joined) the work to get it. Always exactly one entry (the identifier just submitted) — an array for shape-parity with the batch envelope's `fetching` bucket, not because a single read can return more than one. Wait Retry-After seconds, then re-read the same URL — the read is the poll; there is no job resource." } } } }, "400": { "description": "A malformed request — e.g. a batch outside the 1–100 identifier cap, an unrecognized `include` value, `url` and `ids` supplied together, or an unparseable JSON body.", "headers": { "x-request-id": { "description": "On every response, success or failure. Quote it when contacting support — it's the fastest way for Aspire to find exactly your request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "The stable, machine-readable error code. Maps 1:1 to the HTTP status." }, "message": { "type": "string", "description": "Human prose for logs and error screens. Never parse it." }, "details": { "description": "Optional structured extras. Today's one use: a read-miss 404's reason (and retryable, when our fault) — see `details.reason`.", "type": "object", "properties": { "reason": { "type": "string", "description": "Machine-readable, open vocabulary — same values a batch unavailable entry's own `reason` carries." }, "retryable": { "description": "Present (and true) only when the failure was on our side rather than a fact about the entity — retry after a few minutes. Absent means terminal: stop retrying.", "type": "boolean" } }, "required": [ "reason" ] } }, "required": [ "code", "message" ], "description": "The one JSON shape every error response (any status other than 200/202) carries, wrapped under `error` in `apiErrorResponseSchema`." } }, "required": [ "error" ], "description": "The one JSON shape every error response (any status other than 200/202) carries." }, "example": { "error": { "code": "invalid-input", "message": "ids must contain between 1 and 100 identifiers, got 101" } } } } }, "401": { "description": "Missing, malformed, expired, or revoked credential.", "headers": { "x-request-id": { "description": "On every response, success or failure. Quote it when contacting support — it's the fastest way for Aspire to find exactly your request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "The stable, machine-readable error code. Maps 1:1 to the HTTP status." }, "message": { "type": "string", "description": "Human prose for logs and error screens. Never parse it." }, "details": { "description": "Optional structured extras. Today's one use: a read-miss 404's reason (and retryable, when our fault) — see `details.reason`.", "type": "object", "properties": { "reason": { "type": "string", "description": "Machine-readable, open vocabulary — same values a batch unavailable entry's own `reason` carries." }, "retryable": { "description": "Present (and true) only when the failure was on our side rather than a fact about the entity — retry after a few minutes. Absent means terminal: stop retrying.", "type": "boolean" } }, "required": [ "reason" ] } }, "required": [ "code", "message" ], "description": "The one JSON shape every error response (any status other than 200/202) carries, wrapped under `error` in `apiErrorResponseSchema`." } }, "required": [ "error" ], "description": "The one JSON shape every error response (any status other than 200/202) carries." }, "example": { "error": { "code": "unauthorized", "message": "invalid credential" } } } } }, "403": { "description": "Valid credential, but it lacks the `:` permission this operation requires (stated in the operation description).", "headers": { "x-request-id": { "description": "On every response, success or failure. Quote it when contacting support — it's the fastest way for Aspire to find exactly your request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "The stable, machine-readable error code. Maps 1:1 to the HTTP status." }, "message": { "type": "string", "description": "Human prose for logs and error screens. Never parse it." }, "details": { "description": "Optional structured extras. Today's one use: a read-miss 404's reason (and retryable, when our fault) — see `details.reason`.", "type": "object", "properties": { "reason": { "type": "string", "description": "Machine-readable, open vocabulary — same values a batch unavailable entry's own `reason` carries." }, "retryable": { "description": "Present (and true) only when the failure was on our side rather than a fact about the entity — retry after a few minutes. Absent means terminal: stop retrying.", "type": "boolean" } }, "required": [ "reason" ] } }, "required": [ "code", "message" ], "description": "The one JSON shape every error response (any status other than 200/202) carries, wrapped under `error` in `apiErrorResponseSchema`." } }, "required": [ "error" ], "description": "The one JSON shape every error response (any status other than 200/202) carries." }, "example": { "error": { "code": "forbidden", "message": "token lacks creators:read permission" } } } } }, "404": { "description": "A read-miss (branch on `details.reason` — retry only if `details.retryable` is `true`, never on `message` prose), an unknown `asProfile` (deliberately indistinguishable from a nonexistent one, so slugs are not enumerable), or an unsupported network. `details.reason` is an open vocabulary (additions are non-breaking). Values today: `account-not-discoverable` (creators — terminal; a personal account and a nonexistent handle are indistinguishable), `not-supported-on-network` (the network isn't supported yet — terminal until it ships), `outside-recent-media-window` (posts — terminal), `author-unresolved` (posts), `unparseable-identifier`, and `internal-error` with `details.retryable: true` (our fault — retry after a few minutes).", "headers": { "x-request-id": { "description": "On every response, success or failure. Quote it when contacting support — it's the fastest way for Aspire to find exactly your request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "The stable, machine-readable error code. Maps 1:1 to the HTTP status." }, "message": { "type": "string", "description": "Human prose for logs and error screens. Never parse it." }, "details": { "description": "Optional structured extras. Today's one use: a read-miss 404's reason (and retryable, when our fault) — see `details.reason`.", "type": "object", "properties": { "reason": { "type": "string", "description": "Machine-readable, open vocabulary — same values a batch unavailable entry's own `reason` carries." }, "retryable": { "description": "Present (and true) only when the failure was on our side rather than a fact about the entity — retry after a few minutes. Absent means terminal: stop retrying.", "type": "boolean" } }, "required": [ "reason" ] } }, "required": [ "code", "message" ], "description": "The one JSON shape every error response (any status other than 200/202) carries, wrapped under `error` in `apiErrorResponseSchema`." } }, "required": [ "error" ], "description": "The one JSON shape every error response (any status other than 200/202) carries." }, "example": { "error": { "code": "not-found", "message": "no creator found for instagram/somehandle", "details": { "reason": "account-not-discoverable" } } } } } }, "429": { "description": "Over the per-principal request budget (fixed one-minute window; default 60 requests/minute, raisable per Service Account). Rejected requests still count against the window. Honour `Retry-After`.", "headers": { "x-request-id": { "description": "On every response, success or failure. Quote it when contacting support — it's the fastest way for Aspire to find exactly your request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Delta-seconds (RFC 9110 §10.2.3), always ≥ 1. The server controls the backoff — polling faster than this burns rate limit and gets the data no sooner.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "The stable, machine-readable error code. Maps 1:1 to the HTTP status." }, "message": { "type": "string", "description": "Human prose for logs and error screens. Never parse it." }, "details": { "description": "Optional structured extras. Today's one use: a read-miss 404's reason (and retryable, when our fault) — see `details.reason`.", "type": "object", "properties": { "reason": { "type": "string", "description": "Machine-readable, open vocabulary — same values a batch unavailable entry's own `reason` carries." }, "retryable": { "description": "Present (and true) only when the failure was on our side rather than a fact about the entity — retry after a few minutes. Absent means terminal: stop retrying.", "type": "boolean" } }, "required": [ "reason" ] } }, "required": [ "code", "message" ], "description": "The one JSON shape every error response (any status other than 200/202) carries, wrapped under `error` in `apiErrorResponseSchema`." } }, "required": [ "error" ], "description": "The one JSON shape every error response (any status other than 200/202) carries." }, "example": { "error": { "code": "rate-limited", "message": "rate limit exceeded (60 requests/minute for this principal)" } } } } }, "500": { "description": "Our fault. The message is deliberately generic — internal error detail is never exposed. Safe to retry with backoff.", "headers": { "x-request-id": { "description": "On every response, success or failure. Quote it when contacting support — it's the fastest way for Aspire to find exactly your request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "The stable, machine-readable error code. Maps 1:1 to the HTTP status." }, "message": { "type": "string", "description": "Human prose for logs and error screens. Never parse it." }, "details": { "description": "Optional structured extras. Today's one use: a read-miss 404's reason (and retryable, when our fault) — see `details.reason`.", "type": "object", "properties": { "reason": { "type": "string", "description": "Machine-readable, open vocabulary — same values a batch unavailable entry's own `reason` carries." }, "retryable": { "description": "Present (and true) only when the failure was on our side rather than a fact about the entity — retry after a few minutes. Absent means terminal: stop retrying.", "type": "boolean" } }, "required": [ "reason" ] } }, "required": [ "code", "message" ], "description": "The one JSON shape every error response (any status other than 200/202) carries, wrapped under `error` in `apiErrorResponseSchema`." } }, "required": [ "error" ], "description": "The one JSON shape every error response (any status other than 200/202) carries." }, "example": { "error": { "code": "internal-error", "message": "the request could not be completed" } } } } }, "503": { "description": "A dependency needed to verify the credential is unreachable — the credential was neither accepted nor rejected. Retry with backoff.", "headers": { "x-request-id": { "description": "On every response, success or failure. Quote it when contacting support — it's the fastest way for Aspire to find exactly your request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "The stable, machine-readable error code. Maps 1:1 to the HTTP status." }, "message": { "type": "string", "description": "Human prose for logs and error screens. Never parse it." }, "details": { "description": "Optional structured extras. Today's one use: a read-miss 404's reason (and retryable, when our fault) — see `details.reason`.", "type": "object", "properties": { "reason": { "type": "string", "description": "Machine-readable, open vocabulary — same values a batch unavailable entry's own `reason` carries." }, "retryable": { "description": "Present (and true) only when the failure was on our side rather than a fact about the entity — retry after a few minutes. Absent means terminal: stop retrying.", "type": "boolean" } }, "required": [ "reason" ] } }, "required": [ "code", "message" ], "description": "The one JSON shape every error response (any status other than 200/202) carries, wrapped under `error` in `apiErrorResponseSchema`." } }, "required": [ "error" ], "description": "The one JSON shape every error response (any status other than 200/202) carries." }, "example": { "error": { "code": "unavailable", "message": "temporarily unavailable" } } } } } } } ``` --- # Read many posts in one call (request-body form) `POST /posts/batch` Identical to `GET /posts?ids=` in every observable way — same buckets, same cap, same semantics — it exists only because an identifier list can outgrow a URL. Requires `posts:read`. Full operation definition — parameters, request/response schemas, and examples, fully dereferenced against the OpenAPI document: ```json { "operationId": "postPostsBatch", "tags": [ "posts" ], "summary": "Read many posts in one call (request-body form)", "description": "Identical to `GET /posts?ids=` in every observable way — same buckets, same cap, same semantics — it exists only because an identifier list can outgrow a URL. Requires `posts:read`.", "x-required-scope": "posts:read", "requestBody": { "required": true, "description": "The POST twin of the GET `?ids=` form — it exists only because an identifier list can outgrow a URL. `ids` follows the same 1–100 cap and three identifier forms; `network`, `asOrg`, and `asProfile` mean exactly what the query parameters of the same names mean.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "The identifiers to look up, 1–100 per request. Each is qualified (`instagram:somehandle`), a post/profile URL, or bare (resolved against `network`).", "minItems": 1, "maxItems": 100 }, "network": { "description": "Default network for bare identifiers in `ids` (defaults to `instagram`). Never a filter — a qualified (`instagram:handle`) or URL identifier carries its own network.", "type": "string" }, "asOrg": { "description": "Names a target Organization to act on, when it differs from your credential's own organization — for a delegated agency/partner relationship.", "type": "string" }, "asProfile": { "description": "Attribution only — associates this batch's discovery/refresh work with one of your Profiles, resolved within your organization.", "type": "string" } }, "required": [ "ids" ] }, "examples": { "somehandle": { "value": { "ids": [ "instagram:somehandle", "https://www.instagram.com/p/DEF456/" ], "network": "instagram" } } } } } }, "responses": { "200": { "description": "Always 200 — per-item outcomes are buckets, never per-item HTTP statuses.", "headers": { "x-request-id": { "description": "On every response, success or failure. Quote it when contacting support — it's the fastest way for Aspire to find exactly your request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Present iff `fetching` is non-empty — delta-seconds until those entries are worth re-submitting (every fetching entry in one response shares the same instant).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string", "const": "instagram", "description": "The social network this post is on." }, "externalId": { "description": "The post's network-native identifier.", "type": [ "string", "null" ] }, "url": { "description": "The post's public permalink.", "type": [ "string", "null" ] }, "postedAt": { "description": "ISO 8601 timestamp of when the post was published.", "type": [ "string", "null" ] }, "text": { "description": "The post's caption text.", "type": [ "string", "null" ] }, "mediaKind": { "description": "The post's media type — `video`, `image`, or `carousel`.", "enum": [ "video", "image", "carousel", null ], "type": [ "string", "null" ] }, "likeCount": { "description": "Total like count.", "type": [ "number", "null" ] }, "commentCount": { "description": "Total comment count.", "type": [ "number", "null" ] }, "viewCount": { "description": "Total view count.", "type": [ "number", "null" ] }, "shareCount": { "description": "Total share count.", "type": [ "number", "null" ] }, "saveCount": { "description": "Total save count.", "type": [ "number", "null" ] }, "author": { "type": "object", "properties": { "accountId": { "description": "The post author's network-native account identifier.", "type": [ "string", "null" ] }, "username": { "description": "The post author's @handle.", "type": [ "string", "null" ] }, "followersCount": { "description": "Total number of followers the post author has.", "type": [ "number", "null" ] }, "verified": { "description": "Whether the post author's identity is verified on the network.", "type": [ "boolean", "null" ] }, "country": { "description": "The post author's country.", "type": [ "string", "null" ] } }, "required": [ "accountId", "username", "followersCount", "verified", "country" ] }, "instagram": { "type": "object", "properties": { "igMediaId": { "description": "Numeric media id for this post.", "type": [ "string", "null" ] }, "igUserId": { "description": "The Instagram-scoped user id of the post's author.", "type": [ "string", "null" ] }, "authorUsername": { "description": "The post author's @handle (core `author.username` is canonical).", "type": [ "string", "null" ] }, "shortcode": { "description": "Short alphanumeric code for this post, as used in its permalink.", "type": [ "string", "null" ] }, "mediaType": { "description": "The post's raw media-type value (core `mediaKind` is the mapped video/image/carousel value).", "type": [ "string", "null" ] }, "mediaAudioType": { "description": "The type of audio used in the media. Can be `MUSIC` or `ORIGINAL_SOUND`.", "type": [ "string", "null" ] }, "mediaProductType": { "description": "Product-type classification for this media (e.g. feed post, reel, story).", "type": [ "string", "null" ] }, "isSharedToFeed": { "description": "For Reels only. When `true`, the reel can appear in both the Feed and Reels tabs. When `false`, the reel can only appear in the Reels tab.", "type": [ "boolean", "null" ] }, "permalink": { "description": "The post's public URL — same value as core `url`.", "type": [ "string", "null" ] }, "caption": { "description": "The post's caption text — same value as core `text`.", "type": [ "string", "null" ] }, "organicLikeCount": { "description": "Likes attributable to organic (non-paid) delivery only.", "type": [ "number", "null" ] }, "totalLikeCount": { "description": "Total likes across organic and paid delivery — same value as core `likeCount`.", "type": [ "number", "null" ] }, "organicCommentCount": { "description": "Comments attributable to organic delivery only.", "type": [ "number", "null" ] }, "totalCommentCount": { "description": "Total comments across organic and paid delivery — same value as core `commentCount`.", "type": [ "number", "null" ] }, "organicViewCount": { "description": "Views attributable to organic delivery only.", "type": [ "number", "null" ] }, "totalViewCount": { "description": "Total views across organic and paid delivery — same value as core `viewCount`.", "type": [ "number", "null" ] }, "organicRepostCount": { "description": "Reposts (reshares by other accounts) attributable to organic delivery.", "type": [ "number", "null" ] }, "organicSaveCount": { "description": "Saves attributable to organic delivery only.", "type": [ "number", "null" ] }, "organicShareCount": { "description": "Shares attributable to organic delivery only.", "type": [ "number", "null" ] }, "organicReach": { "description": "Distinct accounts that organically saw this post.", "type": [ "number", "null" ] }, "organicTotalInteractions": { "description": "Sum of organic likes, comments, saves, and shares on this post.", "type": [ "number", "null" ] }, "organicFollows": { "description": "Accounts that started following the creator as a direct result of this post (organic only).", "type": [ "number", "null" ] }, "organicProfileVisits": { "description": "Visits to the creator's profile attributable to this post (organic only).", "type": [ "number", "null" ] }, "organicProfileActivity": { "description": "The number of actions people took on the creator's profile after visiting it from this post — bio link clicks, or taps on the call, direction, email, or text buttons (organic only, feed and story posts).", "type": [ "number", "null" ] }, "organicFacebookViews": { "description": "Views of this post's cross-posted copy on Facebook (organic only).", "type": [ "number", "null" ] }, "organicCrosspostedViews": { "description": "Total number of times this post was played, aggregated across Instagram and Facebook (organic only, Reels only).", "type": [ "number", "null" ] }, "organicIgReelsAvgWatchTime": { "description": "Average watch time per view, for Reels (organic only).", "type": [ "number", "null" ] }, "organicIgReelsVideoViewTotalTime": { "description": "Total cumulative watch time across all views, for Reels (organic only).", "type": [ "number", "null" ] }, "organicLinkClicks": { "description": "Clicks on a link included in this post (e.g. a Story link sticker), organic only.", "type": [ "number", "null" ] }, "organicNavigation": { "description": "Total navigation actions taken while viewing this post — the sum of exits, taps forward, taps back, and advances to the next story (organic only, story posts).", "type": [ "number", "null" ] }, "organicReplies": { "description": "Replies sent in response to this post (e.g. Story replies), organic only.", "type": [ "number", "null" ] }, "organicExits": { "description": "Instances of a viewer exiting out of this post entirely (e.g. leaving a Story), organic only.", "type": [ "number", "null" ] }, "organicTapsForward": { "description": "Taps to advance past this post (e.g. tapping forward through a Story), organic only.", "type": [ "number", "null" ] }, "organicTapsBack": { "description": "Taps to go back and re-view this post (e.g. tapping back through a Story), organic only.", "type": [ "number", "null" ] }, "hashtags": { "description": "Hashtags extracted from this post's caption.", "type": "array", "items": { "type": "string" } }, "mentions": { "description": "Accounts mentioned in this post — see `PostMention` fields above.", "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string", "description": "The @handle of the mentioned account." }, "type": { "type": "string", "enum": [ "TAG", "CAPTION", "STORY", "COLLAB", "PAID_PARTNERSHIP" ], "description": "How the mention occurred — `TAG`, `CAPTION`, `STORY`, `COLLAB`, or `PAID_PARTNERSHIP`." }, "resolved": { "type": "boolean", "description": "Whether the mentioned username has been resolved to a known account in our system." }, "inviteStatus": { "type": [ "string", "null" ] } }, "required": [ "username", "type", "resolved", "inviteStatus" ] } } }, "required": [ "igMediaId", "igUserId", "authorUsername", "shortcode", "mediaType", "mediaAudioType", "mediaProductType", "isSharedToFeed", "permalink", "caption", "organicLikeCount", "totalLikeCount", "organicCommentCount", "totalCommentCount", "organicViewCount", "totalViewCount", "organicRepostCount", "organicSaveCount", "organicShareCount", "organicReach", "organicTotalInteractions", "organicFollows", "organicProfileVisits", "organicProfileActivity", "organicFacebookViews", "organicCrosspostedViews", "organicIgReelsAvgWatchTime", "organicIgReelsVideoViewTotalTime", "organicLinkClicks", "organicNavigation", "organicReplies", "organicExits", "organicTapsForward", "organicTapsBack", "hashtags", "mentions" ] }, "updatedAt": { "description": "ISO 8601 timestamp of when this post's current snapshot was produced — how fresh this document is.", "type": [ "string", "null" ] }, "analysis": { "type": "object", "properties": { "narration": { "description": "AI-generated (Gemini multimodal) narration of the video/audio content.", "type": [ "string", "null" ] }, "transcript": { "description": "AI-generated (Gemini multimodal) transcript of spoken audio.", "type": [ "string", "null" ] }, "overlayText": { "description": "AI-detected on-screen text overlays, in detection order.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "languages": { "description": "AI-detected spoken/on-screen languages, as free-text labels.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "aestheticTags": { "description": "AI-generated free-text aesthetic/style tags.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "brandSafety": { "description": "AI-judged brand-safety risk per GARM category — a judged VERDICT, not raw enrichment. `null` if not yet judged, or if the judged shape no longer matches the current GARM taxonomy.", "properties": { "adult_content": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "arms_ammunition": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "crime_harmful_acts": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "death_injury": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "online_piracy": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "hate_speech": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "obscenity_profanity": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "illegal_drugs": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "spam_harmful": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "terrorism": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "debated_sensitive_social_issue": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] }, "misinformation": { "type": "string", "enum": [ "High Risk", "Medium Risk", "Low Risk" ] } }, "required": [ "adult_content", "arms_ammunition", "crime_harmful_acts", "death_injury", "online_piracy", "hate_speech", "obscenity_profanity", "illegal_drugs", "spam_harmful", "terrorism", "debated_sensitive_social_issue", "misinformation" ], "type": [ "object", "null" ] }, "commercialAnalysis": { "description": "AI-detected commercial signals — featured products/brands, calls to action, promo codes, and a 1-5 promotional-intent score.", "properties": { "featuredProducts": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "featuredBrands": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "callToActions": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "promoCodes": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "promotionalIntent": { "type": [ "number", "null" ] } }, "required": [ "featuredProducts", "featuredBrands", "callToActions", "promoCodes", "promotionalIntent" ], "type": [ "object", "null" ] }, "emotionalAnalysis": { "description": "AI-judged primary emotion and tone.", "properties": { "primaryEmotion": { "type": [ "string", "null" ] }, "tone": { "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "primaryEmotion", "tone" ], "type": [ "object", "null" ] }, "productionAnalysis": { "description": "AI-judged production quality and technique signals.", "properties": { "productionQuality": { "type": [ "number", "null" ] }, "cameraTechniques": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "audioStyle": { "type": [ "string", "null" ] }, "lightingStyle": { "type": [ "string", "null" ] } }, "required": [ "productionQuality", "cameraTechniques", "audioStyle", "lightingStyle" ], "type": [ "object", "null" ] }, "vibeAnalysis": { "description": "Opaque AI-generated vibe classification — shape is not fixed; treat as untyped JSON." }, "subjectAnalysis": { "description": "Opaque AI-generated subject classification — shape is not fixed; treat as untyped JSON." }, "commentSentimentLabel": { "description": "AI-judged overall comment sentiment label.", "enum": [ "positive", "neutral", "negative", "mixed", null ], "type": [ "string", "null" ] }, "commentSentimentScore": { "description": "AI-judged overall comment sentiment score.", "type": [ "number", "null" ] }, "commentSentimentSummary": { "description": "AI-generated free-text summary of comment sentiment.", "type": [ "string", "null" ] }, "commentSentimentRationale": { "description": "AI-generated free-text rationale for the sentiment judgment.", "type": [ "string", "null" ] }, "commentSentimentThemes": { "description": "AI-generated free-text comment themes.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "commentSentimentBreakdown": { "description": "AI-judged comment sentiment split into positive/neutral/negative buckets, each a count and percentage of comments analyzed.", "properties": { "positive": { "type": "object", "properties": { "count": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "count", "percentage" ] }, "neutral": { "type": "object", "properties": { "count": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "count", "percentage" ] }, "negative": { "type": "object", "properties": { "count": { "type": "number" }, "percentage": { "type": "number" } }, "required": [ "count", "percentage" ] } }, "required": [ "positive", "neutral", "negative" ], "type": [ "object", "null" ] }, "commentSentimentTotalCommentCount": { "description": "Total comments considered in the sentiment judgment.", "type": [ "number", "null" ] }, "commentSentimentRelevantCommentCount": { "description": "Comments judged relevant to the sentiment analysis — a subset of the total.", "type": [ "number", "null" ] } }, "description": "AI-generated (Gemini multimodal) enrichment preview — opt-in via `?include=` (see the `include` query parameter), one key per requested field. Coverage and shape may change without notice." } }, "required": [ "network", "externalId", "url", "postedAt", "text", "mediaKind", "likeCount", "commentCount", "viewCount", "shareCount", "saveCount", "author", "instagram", "updatedAt" ] }, "description": "Documents we hold — same shape as the single read's 200 body." }, "fetching": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The identifier exactly as submitted." }, "retryAfter": { "type": "string", "description": "ISO 8601 instant — every fetching entry in one response shares the same instant, and the response's Retry-After header (present iff this bucket is non-empty) is its delta-seconds twin." } }, "required": [ "id", "retryAfter" ], "description": "A submitted identifier we don't hold yet — this batch read started (or joined) discovery for it. Re-submit it after Retry-After." } }, "unavailable": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The identifier exactly as submitted." }, "reason": { "type": "string", "description": "Machine-readable, open vocabulary (additions are non-breaking). `outside-recent-media-window` and `author-unresolved` occur on posts only. `internal-error` means the failure was on our side — `retryable` is true." }, "retryable": { "description": "Present, and always true, when the failure was on our side rather than a fact about the entity — retry after a few minutes. Absent means terminal: stop retrying.", "type": "boolean", "const": true } }, "required": [ "id", "reason" ], "description": "A submitted identifier that resolved to 'not obtainable'. Check reason (and retryable) — most values mean stop retrying." } } }, "required": [ "data", "fetching", "unavailable" ], "description": "The three-bucket batch envelope, returned with HTTP 200 always — per-item outcomes are buckets, never per-item HTTP statuses. Every submitted identifier appears in exactly one bucket. The response's Retry-After header is present iff `fetching` is non-empty." }, "examples": { "somehandle": { "value": { "data": [ { "network": "instagram", "externalId": "media-def456", "url": "https://www.instagram.com/p/DEF456/", "postedAt": "2026-08-01T00:00:00.000Z", "text": "a conformance caption", "mediaKind": "image", "likeCount": 12, "commentCount": 1, "viewCount": 110, "shareCount": 3, "saveCount": 2, "author": { "accountId": "ig-def456", "username": "somehandle", "followersCount": 1000, "verified": true, "country": "US" }, "instagram": {}, "updatedAt": "2026-08-01T00:00:00.000Z" } ], "fetching": [ { "id": "https://www.instagram.com/p/FETCH1/", "retryAfter": "2026-08-01T00:30:05.000Z" } ], "unavailable": [ { "id": "https://www.instagram.com/p/GONE123/", "reason": "outside-recent-media-window" } ] } } } } } }, "400": { "description": "A malformed request — e.g. a batch outside the 1–100 identifier cap, an unrecognized `include` value, `url` and `ids` supplied together, or an unparseable JSON body.", "headers": { "x-request-id": { "description": "On every response, success or failure. Quote it when contacting support — it's the fastest way for Aspire to find exactly your request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "The stable, machine-readable error code. Maps 1:1 to the HTTP status." }, "message": { "type": "string", "description": "Human prose for logs and error screens. Never parse it." }, "details": { "description": "Optional structured extras. Today's one use: a read-miss 404's reason (and retryable, when our fault) — see `details.reason`.", "type": "object", "properties": { "reason": { "type": "string", "description": "Machine-readable, open vocabulary — same values a batch unavailable entry's own `reason` carries." }, "retryable": { "description": "Present (and true) only when the failure was on our side rather than a fact about the entity — retry after a few minutes. Absent means terminal: stop retrying.", "type": "boolean" } }, "required": [ "reason" ] } }, "required": [ "code", "message" ], "description": "The one JSON shape every error response (any status other than 200/202) carries, wrapped under `error` in `apiErrorResponseSchema`." } }, "required": [ "error" ], "description": "The one JSON shape every error response (any status other than 200/202) carries." }, "example": { "error": { "code": "invalid-input", "message": "ids must contain between 1 and 100 identifiers, got 101" } } } } }, "401": { "description": "Missing, malformed, expired, or revoked credential.", "headers": { "x-request-id": { "description": "On every response, success or failure. Quote it when contacting support — it's the fastest way for Aspire to find exactly your request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "The stable, machine-readable error code. Maps 1:1 to the HTTP status." }, "message": { "type": "string", "description": "Human prose for logs and error screens. Never parse it." }, "details": { "description": "Optional structured extras. Today's one use: a read-miss 404's reason (and retryable, when our fault) — see `details.reason`.", "type": "object", "properties": { "reason": { "type": "string", "description": "Machine-readable, open vocabulary — same values a batch unavailable entry's own `reason` carries." }, "retryable": { "description": "Present (and true) only when the failure was on our side rather than a fact about the entity — retry after a few minutes. Absent means terminal: stop retrying.", "type": "boolean" } }, "required": [ "reason" ] } }, "required": [ "code", "message" ], "description": "The one JSON shape every error response (any status other than 200/202) carries, wrapped under `error` in `apiErrorResponseSchema`." } }, "required": [ "error" ], "description": "The one JSON shape every error response (any status other than 200/202) carries." }, "example": { "error": { "code": "unauthorized", "message": "invalid credential" } } } } }, "403": { "description": "Valid credential, but it lacks the `:` permission this operation requires (stated in the operation description).", "headers": { "x-request-id": { "description": "On every response, success or failure. Quote it when contacting support — it's the fastest way for Aspire to find exactly your request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "The stable, machine-readable error code. Maps 1:1 to the HTTP status." }, "message": { "type": "string", "description": "Human prose for logs and error screens. Never parse it." }, "details": { "description": "Optional structured extras. Today's one use: a read-miss 404's reason (and retryable, when our fault) — see `details.reason`.", "type": "object", "properties": { "reason": { "type": "string", "description": "Machine-readable, open vocabulary — same values a batch unavailable entry's own `reason` carries." }, "retryable": { "description": "Present (and true) only when the failure was on our side rather than a fact about the entity — retry after a few minutes. Absent means terminal: stop retrying.", "type": "boolean" } }, "required": [ "reason" ] } }, "required": [ "code", "message" ], "description": "The one JSON shape every error response (any status other than 200/202) carries, wrapped under `error` in `apiErrorResponseSchema`." } }, "required": [ "error" ], "description": "The one JSON shape every error response (any status other than 200/202) carries." }, "example": { "error": { "code": "forbidden", "message": "token lacks creators:read permission" } } } } }, "404": { "description": "A read-miss (branch on `details.reason` — retry only if `details.retryable` is `true`, never on `message` prose), an unknown `asProfile` (deliberately indistinguishable from a nonexistent one, so slugs are not enumerable), or an unsupported network. `details.reason` is an open vocabulary (additions are non-breaking). Values today: `account-not-discoverable` (creators — terminal; a personal account and a nonexistent handle are indistinguishable), `not-supported-on-network` (the network isn't supported yet — terminal until it ships), `outside-recent-media-window` (posts — terminal), `author-unresolved` (posts), `unparseable-identifier`, and `internal-error` with `details.retryable: true` (our fault — retry after a few minutes).", "headers": { "x-request-id": { "description": "On every response, success or failure. Quote it when contacting support — it's the fastest way for Aspire to find exactly your request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "The stable, machine-readable error code. Maps 1:1 to the HTTP status." }, "message": { "type": "string", "description": "Human prose for logs and error screens. Never parse it." }, "details": { "description": "Optional structured extras. Today's one use: a read-miss 404's reason (and retryable, when our fault) — see `details.reason`.", "type": "object", "properties": { "reason": { "type": "string", "description": "Machine-readable, open vocabulary — same values a batch unavailable entry's own `reason` carries." }, "retryable": { "description": "Present (and true) only when the failure was on our side rather than a fact about the entity — retry after a few minutes. Absent means terminal: stop retrying.", "type": "boolean" } }, "required": [ "reason" ] } }, "required": [ "code", "message" ], "description": "The one JSON shape every error response (any status other than 200/202) carries, wrapped under `error` in `apiErrorResponseSchema`." } }, "required": [ "error" ], "description": "The one JSON shape every error response (any status other than 200/202) carries." }, "example": { "error": { "code": "not-found", "message": "no creator found for instagram/somehandle", "details": { "reason": "account-not-discoverable" } } } } } }, "429": { "description": "Over the per-principal request budget (fixed one-minute window; default 60 requests/minute, raisable per Service Account). Rejected requests still count against the window. Honour `Retry-After`.", "headers": { "x-request-id": { "description": "On every response, success or failure. Quote it when contacting support — it's the fastest way for Aspire to find exactly your request.", "schema": { "type": "string" } }, "Retry-After": { "description": "Delta-seconds (RFC 9110 §10.2.3), always ≥ 1. The server controls the backoff — polling faster than this burns rate limit and gets the data no sooner.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "The stable, machine-readable error code. Maps 1:1 to the HTTP status." }, "message": { "type": "string", "description": "Human prose for logs and error screens. Never parse it." }, "details": { "description": "Optional structured extras. Today's one use: a read-miss 404's reason (and retryable, when our fault) — see `details.reason`.", "type": "object", "properties": { "reason": { "type": "string", "description": "Machine-readable, open vocabulary — same values a batch unavailable entry's own `reason` carries." }, "retryable": { "description": "Present (and true) only when the failure was on our side rather than a fact about the entity — retry after a few minutes. Absent means terminal: stop retrying.", "type": "boolean" } }, "required": [ "reason" ] } }, "required": [ "code", "message" ], "description": "The one JSON shape every error response (any status other than 200/202) carries, wrapped under `error` in `apiErrorResponseSchema`." } }, "required": [ "error" ], "description": "The one JSON shape every error response (any status other than 200/202) carries." }, "example": { "error": { "code": "rate-limited", "message": "rate limit exceeded (60 requests/minute for this principal)" } } } } }, "500": { "description": "Our fault. The message is deliberately generic — internal error detail is never exposed. Safe to retry with backoff.", "headers": { "x-request-id": { "description": "On every response, success or failure. Quote it when contacting support — it's the fastest way for Aspire to find exactly your request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "The stable, machine-readable error code. Maps 1:1 to the HTTP status." }, "message": { "type": "string", "description": "Human prose for logs and error screens. Never parse it." }, "details": { "description": "Optional structured extras. Today's one use: a read-miss 404's reason (and retryable, when our fault) — see `details.reason`.", "type": "object", "properties": { "reason": { "type": "string", "description": "Machine-readable, open vocabulary — same values a batch unavailable entry's own `reason` carries." }, "retryable": { "description": "Present (and true) only when the failure was on our side rather than a fact about the entity — retry after a few minutes. Absent means terminal: stop retrying.", "type": "boolean" } }, "required": [ "reason" ] } }, "required": [ "code", "message" ], "description": "The one JSON shape every error response (any status other than 200/202) carries, wrapped under `error` in `apiErrorResponseSchema`." } }, "required": [ "error" ], "description": "The one JSON shape every error response (any status other than 200/202) carries." }, "example": { "error": { "code": "internal-error", "message": "the request could not be completed" } } } } }, "503": { "description": "A dependency needed to verify the credential is unreachable — the credential was neither accepted nor rejected. Retry with backoff.", "headers": { "x-request-id": { "description": "On every response, success or failure. Quote it when contacting support — it's the fastest way for Aspire to find exactly your request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "The stable, machine-readable error code. Maps 1:1 to the HTTP status." }, "message": { "type": "string", "description": "Human prose for logs and error screens. Never parse it." }, "details": { "description": "Optional structured extras. Today's one use: a read-miss 404's reason (and retryable, when our fault) — see `details.reason`.", "type": "object", "properties": { "reason": { "type": "string", "description": "Machine-readable, open vocabulary — same values a batch unavailable entry's own `reason` carries." }, "retryable": { "description": "Present (and true) only when the failure was on our side rather than a fact about the entity — retry after a few minutes. Absent means terminal: stop retrying.", "type": "boolean" } }, "required": [ "reason" ] } }, "required": [ "code", "message" ], "description": "The one JSON shape every error response (any status other than 200/202) carries, wrapped under `error` in `apiErrorResponseSchema`." } }, "required": [ "error" ], "description": "The one JSON shape every error response (any status other than 200/202) carries." }, "example": { "error": { "code": "unavailable", "message": "temporarily unavailable" } } } } } } } ```