Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: ScrapeField Instagram API
version: 1.0.0
summary: One API for Google Maps, LinkedIn, Instagram, TikTok and X.
description: 'One key, one invoice, five platforms — and each platform''s data in its own shape. A Google Maps place is named the way Google''s Places API names it, an Instagram post the way the Graph API does, a TikTok video the way TikTok''s own APIs do, an X post the way X''s API v2 does; LinkedIn, which has no official data API, uses the words it prints.
**Conventions.** The same everywhere: the `{ data, meta }` envelope, snake_case, ISO 8601 UTC timestamps, the platform''s own ids as strings, and every documented key present on every object.
**Pricing.** Every endpoint has a published credit cost, carried here as `x-credits`. Multiply by your volume to get your bill — there are no plans and no tiers, just credits. A call we fail is refunded automatically and the reversal appears in your usage ledger.
**Pagination.** Cursor only. Pass `meta.next_cursor` back as `cursor`; `null` means the last page. A page holds at most `limit` rows, sometimes fewer; an endpoint without `limit` has a fixed page size, given in its description. A cursor lasts as long as the answer is cached (hours); after that it is refused with `invalid_cursor`.
**Demo.** Any data endpoint answers with no key when you add `?demo=true`: a fixed answer in the same shape, charged nothing.
**Nulls.** A field is `null` when the platform does not expose it — never 0 and never a guess.'
contact:
name: Support
url: https://scrapefield.com/contact
email: support@scrapefield.com
servers:
- url: https://api.scrapefield.com/v1
security:
- bearerAuth: []
tags:
- name: Instagram
paths:
/instagram/profile:
get:
operationId: get_instagram_profile
summary: Get an Instagram profile
description: 'Fetch an Instagram account: username, name, biography, bio_links, followers_count, follows_count, media_count, is_verified, is_private, is_business_account, category and the business contact buttons — named as in Instagram''s Graph API. Use this for creator discovery and audience sizing.
Give exactly one of `username` or `url` to identify the profile.
Costs 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.'
tags:
- Instagram
x-credits: 3
x-cache-ttl-seconds: 43200
x-mcp-tool: get_instagram_profile
security:
- bearerAuth: []
- {}
parameters:
- name: username
in: query
required: false
description: The username. A leading @ is fine.
schema:
type: string
pattern: ^(?:@?[A-Za-z0-9._]{1,30})$
maxLength: 2048
example: nasa
- name: url
in: query
required: false
description: The profile URL.
schema:
type: string
pattern: ^(?:(https?://)?((www|m)\.)?instagram\.com/[A-Za-z0-9._]{1,30}([/?#]\S*)?)$
maxLength: 2048
- name: fresh
in: query
required: false
description: Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.
schema:
type: boolean
default: false
- name: demo
in: query
required: false
description: 'With no key: a fixed demo answer in the same shape, charged nothing.'
schema:
type: boolean
default: false
responses:
'200':
description: The request succeeded.
content:
application/json:
schema:
type: object
required:
- data
- meta
properties:
data:
$ref: '#/components/schemas/instagram_profile'
meta:
$ref: '#/components/schemas/meta'
'400':
$ref: '#/components/responses/error'
'401':
$ref: '#/components/responses/error'
'403':
$ref: '#/components/responses/error'
'404':
$ref: '#/components/responses/error'
'429':
$ref: '#/components/responses/error'
'500':
$ref: '#/components/responses/error'
'501':
$ref: '#/components/responses/error'
'502':
$ref: '#/components/responses/error'
/instagram/posts:
get:
operationId: get_instagram_posts
summary: Get recent posts from an Instagram profile
description: 'Fetch recent posts and Reels by one Instagram account: shortcode, permalink, media_type, caption, timestamp, media_url, carousel children, like_count, comments_count, view_count, hashtags, mentions and the paid-partnership label.
Give exactly one of `username` or `url` to identify the profile.
Costs 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.'
tags:
- Instagram
x-credits: 3
x-cache-ttl-seconds: 10800
x-mcp-tool: get_instagram_posts
security:
- bearerAuth: []
- {}
parameters:
- name: username
in: query
required: false
description: The username. A leading @ is fine.
schema:
type: string
pattern: ^(?:@?[A-Za-z0-9._]{1,30})$
maxLength: 2048
example: nasa
- name: url
in: query
required: false
description: The profile URL.
schema:
type: string
pattern: ^(?:(https?://)?((www|m)\.)?instagram\.com/[A-Za-z0-9._]{1,30}([/?#]\S*)?)$
maxLength: 2048
- name: limit
in: query
required: false
description: 'At most this many results, 1–24. A page can hold fewer while `next_cursor` is set: read until it is null.'
schema:
type: integer
minimum: 1
maximum: 24
default: 24
- name: cursor
in: query
required: false
description: The `meta.next_cursor` from the previous page. Omit for the first page.
schema:
type: string
maxLength: 2048
- name: fresh
in: query
required: false
description: Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.
schema:
type: boolean
default: false
- name: demo
in: query
required: false
description: 'With no key: a fixed demo answer in the same shape, charged nothing.'
schema:
type: boolean
default: false
responses:
'200':
description: The request succeeded.
content:
application/json:
schema:
type: object
required:
- data
- meta
properties:
data:
type: array
items:
$ref: '#/components/schemas/instagram_post'
meta:
$ref: '#/components/schemas/meta'
'400':
$ref: '#/components/responses/error'
'401':
$ref: '#/components/responses/error'
'403':
$ref: '#/components/responses/error'
'404':
$ref: '#/components/responses/error'
'429':
$ref: '#/components/responses/error'
'500':
$ref: '#/components/responses/error'
'501':
$ref: '#/components/responses/error'
'502':
$ref: '#/components/responses/error'
/instagram/post:
get:
operationId: get_instagram_post
summary: Get one Instagram post
description: 'Fetch one Instagram post or Reel by its URL or shortcode: caption, media, username, timestamp, like_count, comments_count and view_count.
Give exactly one of `url` or `shortcode` to identify the post.
Costs 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.'
tags:
- Instagram
x-credits: 3
x-cache-ttl-seconds: 10800
x-mcp-tool: get_instagram_post
security:
- bearerAuth: []
- {}
parameters:
- name: url
in: query
required: false
description: The post URL.
schema:
type: string
pattern: ^(?:(https?://)?((www|m)\.)?instagram\.com/([A-Za-z0-9._]{1,30}/)?(p|reel|reels|tv)/[A-Za-z0-9_-]{5,40}([/?#]\S*)?)$
maxLength: 2048
- name: shortcode
in: query
required: false
description: The shortcode from the URL, e.g. `C1a2B3c4D5e`.
schema:
type: string
pattern: ^(?:[A-Za-z0-9_-]{5,40})$
maxLength: 2048
example: C1a2B3c4D5e
- name: fresh
in: query
required: false
description: Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.
schema:
type: boolean
default: false
- name: demo
in: query
required: false
description: 'With no key: a fixed demo answer in the same shape, charged nothing.'
schema:
type: boolean
default: false
responses:
'200':
description: The request succeeded.
content:
application/json:
schema:
type: object
required:
- data
- meta
properties:
data:
$ref: '#/components/schemas/instagram_post'
meta:
$ref: '#/components/schemas/meta'
'400':
$ref: '#/components/responses/error'
'401':
$ref: '#/components/responses/error'
'403':
$ref: '#/components/responses/error'
'404':
$ref: '#/components/responses/error'
'429':
$ref: '#/components/responses/error'
'500':
$ref: '#/components/responses/error'
'501':
$ref: '#/components/responses/error'
'502':
$ref: '#/components/responses/error'
/instagram/comments:
get:
operationId: get_instagram_comments
summary: Get the comments on an Instagram post
description: 'Fetch comments on one Instagram post: username, text, timestamp, like_count, reply_count and parent_id for replies. Use this for social listening and campaign verification.
Give exactly one of `url` or `shortcode` to identify the post.
Costs 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.'
tags:
- Instagram
x-credits: 3
x-cache-ttl-seconds: 3600
x-mcp-tool: get_instagram_comments
security:
- bearerAuth: []
- {}
parameters:
- name: url
in: query
required: false
description: The post URL.
schema:
type: string
pattern: ^(?:(https?://)?((www|m)\.)?instagram\.com/([A-Za-z0-9._]{1,30}/)?(p|reel|reels|tv)/[A-Za-z0-9_-]{5,40}([/?#]\S*)?)$
maxLength: 2048
- name: shortcode
in: query
required: false
description: The post shortcode.
schema:
type: string
pattern: ^(?:[A-Za-z0-9_-]{5,40})$
maxLength: 2048
example: C1a2B3c4D5e
- name: limit
in: query
required: false
description: 'At most this many results, 1–50. A page can hold fewer while `next_cursor` is set: read until it is null.'
schema:
type: integer
minimum: 1
maximum: 50
default: 50
- name: cursor
in: query
required: false
description: The `meta.next_cursor` from the previous page. Omit for the first page.
schema:
type: string
maxLength: 2048
- name: fresh
in: query
required: false
description: Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.
schema:
type: boolean
default: false
- name: demo
in: query
required: false
description: 'With no key: a fixed demo answer in the same shape, charged nothing.'
schema:
type: boolean
default: false
responses:
'200':
description: The request succeeded.
content:
application/json:
schema:
type: object
required:
- data
- meta
properties:
data:
type: array
items:
$ref: '#/components/schemas/instagram_comment'
meta:
$ref: '#/components/schemas/meta'
'400':
$ref: '#/components/responses/error'
'401':
$ref: '#/components/responses/error'
'403':
$ref: '#/components/responses/error'
'404':
$ref: '#/components/responses/error'
'429':
$ref: '#/components/responses/error'
'500':
$ref: '#/components/responses/error'
'501':
$ref: '#/components/responses/error'
'502':
$ref: '#/components/responses/error'
/instagram/hashtag:
get:
operationId: get_instagram_hashtag
summary: Get recent posts for an Instagram hashtag
description: 'Fetch recent posts carrying one hashtag, each a full post. Use this for trend and campaign monitoring.
Costs 64 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.'
tags:
- Instagram
x-credits: 64
x-cache-ttl-seconds: 3600
x-mcp-tool: get_instagram_hashtag
security:
- bearerAuth: []
- {}
parameters:
- name: tag
in: query
required: true
description: 'The hashtag, without the leading #.'
schema:
type: string
pattern: ^(?:#?[^\s#/?&]{1,100})$
maxLength: 2048
example: sourdough
- name: limit
in: query
required: false
description: 'At most this many results, 1–24. A page can hold fewer while `next_cursor` is set: read until it is null.'
schema:
type: integer
minimum: 1
maximum: 24
default: 24
- name: cursor
in: query
required: false
description: The `meta.next_cursor` from the previous page. Omit for the first page.
schema:
type: string
maxLength: 2048
- name: fresh
in: query
required: false
description: Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.
schema:
type: boolean
default: false
- name: demo
in: query
required: false
description: 'With no key: a fixed demo answer in the same shape, charged nothing.'
schema:
type: boolean
default: false
responses:
'200':
description: The request succeeded.
content:
application/json:
schema:
type: object
required:
- data
- meta
properties:
data:
type: array
items:
$ref: '#/components/schemas/instagram_post'
meta:
$ref: '#/components/schemas/meta'
'400':
$ref: '#/components/responses/error'
'401':
$ref: '#/components/responses/error'
'403':
$ref: '#/components/responses/error'
'404':
$ref: '#/components/responses/error'
'429':
$ref: '#/components/responses/error'
'500':
$ref: '#/components/responses/error'
'501':
$ref: '#/components/responses/error'
'502':
$ref: '#/components/responses/error'
/instagram/search:
get:
operationId: search_instagram_accounts
summary: Search Instagram accounts
description: 'Find Instagram accounts by a keyword: each account''s username, name and link, the most relevant first, one page. The search answers from a search index, so it gives no counts: call `instagram/profile` with a username for the whole account. Use this to find creators and brands when you do not have a username.
Costs 3 credits, whether the answer is fetched or served from cache. A failed call is refunded automatically.'
tags:
- Instagram
x-credits: 3
x-cache-ttl-seconds: 86400
x-mcp-tool: search_instagram_accounts
security:
- bearerAuth: []
- {}
parameters:
- name: query
in: query
required: true
description: Words to search for, e.g. "sourdough bakery".
schema:
type: string
maxLength: 2048
example: ferrari
- name: limit
in: query
required: false
description: 'At most this many results, 1–50. A page can hold fewer while `next_cursor` is set: read until it is null.'
schema:
type: integer
minimum: 1
maximum: 50
default: 25
- name: fresh
in: query
required: false
description: Skip the cache and fetch now. Charged normally. Not available on trial credits — buy any pack to unlock it.
schema:
type: boolean
default: false
- name: demo
in: query
required: false
description: 'With no key: a fixed demo answer in the same shape, charged nothing.'
schema:
type: boolean
default: false
responses:
'200':
description: The request succeeded.
content:
application/json:
schema:
type: object
required:
- data
- meta
properties:
data:
type: array
items:
$ref: '#/components/schemas/instagram_search_result'
meta:
$ref: '#/components/schemas/meta'
'400':
$ref: '#/components/responses/error'
'401':
$ref: '#/components/responses/error'
'403':
$ref: '#/components/responses/error'
'404':
$ref: '#/components/responses/error'
'429':
$ref: '#/components/responses/error'
'500':
$ref: '#/components/responses/error'
'501':
$ref: '#/components/responses/error'
'502':
$ref: '#/components/responses/error'
components:
responses:
error:
description: Something went wrong. `error.code` is stable; `error.message` says what to do next.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
schemas:
instagram_post:
type: object
required:
- id
- shortcode
- permalink
- media_type
- media_product_type
- caption
- timestamp
- username
- media_url
- thumbnail_url
- children
- video_duration
- like_count
- comments_count
- view_count
- hashtags
- mentions
- location
- is_paid_partnership
properties:
id:
type: string
description: Instagram's numeric id for the post.
shortcode:
type: string
description: The code in the URL, e.g. `C1a2B3c4D5e`.
permalink:
type: string
format: uri
description: The post.
media_type:
type: string
enum:
- IMAGE
- VIDEO
- CAROUSEL_ALBUM
description: As the Graph API names them.
media_product_type:
type: string
enum:
- FEED
- REELS
description: A grid post or a Reel.
caption:
type:
- string
- 'null'
description: The caption.
timestamp:
type:
- string
- 'null'
format: date-time
description: When it was posted. `null` when the source does not say.
username:
type: string
description: Who posted it.
media_url:
type: string
format: uri
description: The image, or the video file. A carousel's first item. On Instagram's CDN. Instagram signs the link, and it stops working within a few days, so fetch the file soon. We do not rehost media.
thumbnail_url:
type:
- string
- 'null'
format: uri
description: The cover of a video. On Instagram's CDN. Instagram signs the link, and it stops working within a few days, so fetch the file soon. We do not rehost media.
children:
type: array
items:
type: object
required:
- media_type
- media_url
properties:
media_type:
type: string
enum:
- IMAGE
- VIDEO
description: An image or a video.
media_url:
type: string
format: uri
description: The image, or the video file. On Instagram's CDN. Instagram signs the link, and it stops working within a few days, so fetch the file soon. We do not rehost media.
additionalProperties: false
description: A carousel's items, in order. Empty for a single image or video.
video_duration:
type:
- number
- 'null'
description: Seconds.
like_count:
type:
- integer
- 'null'
description: '`null` when the owner has hidden it.'
comments_count:
type:
- integer
- 'null'
description: '`null` when the source does not give it.'
view_count:
type:
- integer
- 'null'
description: Views, for videos and Reels.
hashtags:
type: array
items:
type: string
description: One hashtag.
description: 'The caption''s hashtags, without the #.'
mentions:
type: array
items:
type: string
description: One username.
description: The usernames the caption mentions, without the @.
location:
type:
- object
- 'null'
required:
- id
- name
properties:
id:
type: string
description: Instagram's id for the location.
name:
type: string
description: The place's name, as the tag shows it.
additionalProperties: false
description: The location tag.
is_paid_partnership:
type:
- boolean
- 'null'
description: Whether it carries the "Paid partnership" label. `null` where that is not known.
additionalProperties: false
description: An Instagram post or Reel.
instagram_search_result:
type: object
required:
- username
- name
- url
properties:
username:
type: string
description: Without the @.
name:
type:
- string
- 'null'
description: The display name, as the search index has it.
url:
type: string
format: uri
description: The account's page.
additionalProperties: false
description: An Instagram account that a search found. Call `instagram/profile` with its username for the whole account.
meta:
type: object
required:
- request_id
- credits_charged
- cached
- fetched_at
- next_cursor
properties:
request_id:
type: string
description: Quote this if you contact support.
credits_charged:
type: integer
description: 'The endpoint''s published cost. 0 for a demo answer, and for a list emptied because everyone in it asked not to be served. A failed call has no `meta`: it answers with an error, and is refunded.'
credits_remaining:
type: integer
cached:
type: boolean
fetched_at:
type: string
format: date-time
description: When the data was actually fetched — the original time on a cache hit, so freshness is always visible.
next_cursor:
type:
- string
- 'null'
description: Pass as `cursor` for the next page. `null` on the last page. It lasts as long as the answer is cached.
demo:
type: boolean
description: Present, and true, on a demo answer (`?demo=true` with no key).
note:
type: string
description: 'On a demo answer: what it is, and what a live call costs.'
error:
type: object
required:
- error
properties:
error:
type: object
required:
- type
- code
- message
- request_id
properties:
type:
type: string
enum:
- invalid_request
- authentication_error
- method_not_allowed
- permission_error
- not_found
- rate_limit
- upstream_error
- not_available
- internal_error
code:
type: string
description: Stable and documented. Branch on this, not on the message.
enum:
- key_in_url
- missing_api_key
- invalid_api_key
- insufficient_credits
- account_suspended
- scope_not_allowed
- fresh_not_available
- disposable_email
- signup_rate_limit
- invalid_link
- link_used
- link_expired
- email_rate_limit
- sign_in_rate_limit
- account_closed
- key_limit
- unverified_account
- unknown_endpoint
- missing_parameter
- missing_one_of
- invalid_parameter
- invalid_json
- invalid_cursor
- profile_not_found
- place_not_found
- subject_suppressed
- signup_not_found
- post_not_found
- posting_not_found
- group_not_found
- ad_not_found
- community_not_found
- endpoint_busy
- concurrency_limit
- method_not_allowed
- not_found_limit
- demo_limit
- not_available_yet
- upstream_unavailable
- internal_error
message:
type: string
description: Written for a human and says what to do next. May change.
docs:
type: string
request_id:
type: string
retry_after:
type: integer
description: 'On a 429: seconds to wait, as the `Retry-After` header says.'
instagram_profile:
type: object
required:
- id
- username
- name
- biography
- website
- bio_links
- profile_picture_url
- followers_count
- follows_count
- media_count
- is_verified
- is_private
- is_business_account
- category
- business_email
- business_phone_number
- highlight_reel_count
properties:
id:
type: string
description: Instagram's numeric id for the account.
username:
type: string
description: Without the @.
name:
type:
- string
- 'null'
description: The display name.
biography:
type:
- string
- 'null'
description: The bio.
website:
type:
- string
- 'null'
format: uri
description: The link in the bio.
bio_links:
type: array
items:
type: object
required:
- title
- url
properties:
title:
type:
- string
- 'null'
description: The link's label, where it has one.
url:
type: string
format: uri
description: Where the link leads.
additionalProperties: false
description: Every link in the bio.
profile_picture_url:
type:
- string
- 'null'
format: uri
description: The profile picture. On Instagram's CDN. Instagram signs the link, and it stops working within a few days, so fetch the file soon. We do not rehost media.
followers_count:
type:
- integer
- 'null'
description: '`null` when the source does not give it.'
follows_count:
type:
- integer
- 'null'
description: '`null` when the source does not give it.'
media_count:
type:
- integer
- 'null'
description: Posts on the grid.
is_verified:
type: boolean
description: Whether the account has the verified badge.
is_private:
type: boolean
description: A private account shows its counts and nothing else.
is_business_account:
type:
- boolean
- 'null'
description: A business or creator account.
category:
type:
- string
- 'null'
description: The label under the name, e.g. "Bakery" or "Public figure".
business_email:
type:
- string
- 'null'
description: Behind the Email button, where a business account shows one.
business_phone_number:
type:
- string
- 'null'
description: Behind the Call button.
highlight_reel_count:
type:
- integer
- 'null'
description: Story highlights on the profile.
additionalProperties: false
description: An Instagram account.
instagram_comment:
type: object
required:
- id
- media_id
- parent_id
- username
- text
- timestamp
- like_count
- reply_count
properties:
id:
type: string
description: Instagram's id for the comment.
media_id:
type: string
description: The post it is on.
parent_id:
type:
- string
- 'null'
description: The comment it replies to. `null` for a top-level comment.
username:
type: string
description: Who wrote it, without the @.
text:
type:
- string
- 'null'
description: '`null` for a comment with no words, such as a GIF.'
timestamp:
type:
- string
- 'null'
format: date-time
description: '`null` when the source does not say.'
like_count:
type:
- integer
- 'null'
description: '`null` when the source does not give it.'
reply_count:
type:
- integer
- 'null'
description: '`null` when the source does not give it.'
additionalProperties: false
description: A comment on an Instagram post.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'Your API key: `Authorization: Bearer sf_live_…`'