/v2/instagram/user/posts
Posts
Get public posts and reels with pagination. Play counts may be inaccurate and exclude Facebook views. Check access-response messages, not just HTTP status.
| Credit cost | Default: 1 credit How charges are determinedCost is decided per call, not per endpoint: the same operation can cost different amounts depending on what it returns. A call that fails costs 0 credits. A result served from cache costs 0 credits. `default` is the cost when no rule matches. Rules are evaluated in order and the first whose conditions all hold wins. A `when` condition is one of: `param` (the request parameter is true), `outcome` (the classifier's outcome), `empty` / `nonEmpty` (a response field is empty and absent, or a non-empty array or string), `flag` (a response field is exactly true). A cost of `{ perStartedMinute: n, of: [fields] }` is n x max(1, ceil(seconds / 60)), so even a short result bills at least one minute. |
|---|---|
| Cache support | Not specified in the published contract. |
| Pagination | No explicit pagination metadata in the published contract. Consult the parameters and response fields below. |
Parameters
| Name | Location / required | Schema |
|---|---|---|
handleInstagram handle | query / required |
|
require_play_countsSet true to require play_count on returned videos (0 is valid). Missing counts return an uncharged error. Why counts can be missing. | query / optional |
|
trimSet to true for a trimmed response. | query / optional |
|
next_max_idPass next_max_id from the previous response for the next page. | query / optional |
|
Request examples
Replace placeholder values and supply your own API key. For operations with a request body, populate the body using the schema above.
cURL
curl --request GET 'https://api.fetchproof.com/v2/instagram/user/posts?handle=YOUR_HANDLE' \
--header 'x-api-key: YOUR_API_KEY'JavaScript
const response = await fetch("https://api.fetchproof.com/v2/instagram/user/posts?handle=YOUR_HANDLE", {
method: 'GET',
headers: { 'x-api-key': process.env.FETCHPROOF_API_KEY }
});
console.log(await response.text());Python
import os
import requests
response = requests.get("https://api.fetchproof.com/v2/instagram/user/posts?handle=YOUR_HANDLE",
headers={"x-api-key": os.environ["FETCHPROOF_API_KEY"]})
print(response.text)Responses
200Success. Envelope: success / credits_remaining / credits_charged.
application/json
object
successrequired
boolean
credits_remainingrequired
integer
credits_chargedrequired
integer
profile_grid_itemsoptional
null
profile_grid_items_cursoroptional
null
pinned_profile_grid_items_idsoptional
null
special_empty_stateoptional
null
num_resultsrequired
integer
more_availablerequired
boolean
itemsrequired
array
Array items
object
pkoptional
string
idrequired
string
fbidoptional
string
device_timestampoptional
integer
caption_is_editedoptional
boolean
strong_id__optional
string
deleted_reasonoptional
integer
has_shared_to_fboptional
integer
has_delayed_metadataoptional
boolean
mezql_tokenoptional
string
share_count_disabledoptional
boolean
should_request_adsoptional
boolean
is_reshare_of_text_post_app_media_in_igoptional
boolean
integrity_review_decisionoptional
string
client_cache_keyoptional
string
is_visual_reply_commenter_notice_enabledoptional
boolean
like_and_view_counts_disabledoptional
boolean
is_post_live_clips_mediaoptional
boolean
is_quiet_postoptional
boolean
profile_grid_thumbnail_fitting_styleoptional
string
comment_threading_enabledoptional
boolean
is_unified_videooptional
boolean
commerciality_statusoptional
string
has_privately_likedoptional
boolean
filter_typeoptional
integer
taken_atrequired
integer
created_atoptional
string
{
"format": "date-time"
}usertagsoptional
object
inrequired
array
Array items
object
positionrequired
array
Array items
schema
anyOf
integer
anyOf
schema
anyOf
number
anyOf
integer
userrequired
object
pkrequired
string
pk_idoptional
string
idrequired
string
usernamerequired
string
full_namerequired
string
is_privaterequired
boolean
strong_id__required
string
is_verifiedrequired
boolean
profile_pic_idrequired
string
profile_pic_urlrequired
string
photo_of_youoptional
boolean
can_see_insights_as_brandoptional
boolean
media_typerequired
integer
coderequired
string
captionrequired
object
bit_flagsrequired
integer
created_atrequired
integer
created_at_utcrequired
integer
did_report_as_spamrequired
boolean
is_ranked_commentrequired
boolean
pkrequired
string
share_enabledrequired
boolean
content_typerequired
string
media_idrequired
string
statusrequired
string
typerequired
integer
user_idoptional
string
strong_id__required
string
textrequired
string
userrequired
object
pkoptional
string
pk_idoptional
string
idrequired
string
usernamerequired
string
full_namerequired
string
is_privaterequired
boolean
is_unpublishedoptional
boolean
strong_id__required
string
fbid_v2required
string
is_verifiedrequired
boolean
profile_pic_idrequired
string
profile_pic_urlrequired
string
is_coveredrequired
boolean
private_reply_statusrequired
integer
has_translationoptional
null
sharing_friction_infooptional
object
bloks_app_urlrequired
null
should_have_sharing_frictionrequired
boolean
sharing_friction_payloadrequired
null
timeline_pinned_user_idsoptional
array
play_countrequired
integer
has_views_fetchingoptional
boolean
ig_play_countrequired
integer
creator_viewer_insightsoptional
array
display_urirequired
string
fb_user_tagsoptional
object
inrequired
array
coauthor_producersoptional
array
Array items
object
__typenamerequired
string
full_namerequired
string
is_verifiedrequired
boolean
profile_pic_urlrequired
string
usernamerequired
string
pkrequired
string
coauthor_producer_can_see_organic_insightsoptional
boolean
invited_coauthor_producersoptional
array
is_in_profile_gridoptional
boolean
profile_grid_control_enabledoptional
boolean
media_cropping_infooptional
object
four_by_three_croprequired
object
crop_leftrequired
integer
crop_rightrequired
integer
crop_toprequired
number
crop_bottomrequired
number
userrequired
object
fbid_v2required
string
feed_post_reshare_disabledrequired
boolean
full_namerequired
string
idrequired
string
is_privaterequired
boolean
is_unpublishedrequired
boolean
pkrequired
string
pk_idoptional
string
show_account_transparency_detailsrequired
boolean
strong_id__required
string
third_party_downloads_enabledrequired
integer
usernamerequired
string
account_typerequired
integer
account_badgesoptional
array
fan_club_inforequired
object
autosave_to_exclusive_highlightrequired
null
connected_member_countrequired
null
fan_club_idrequired
null
fan_club_namerequired
null
has_created_sscoptional
null
has_enough_subscribers_for_sscrequired
null
is_fan_club_gifting_eligiblerequired
null
is_fan_club_referral_eligiblerequired
null
is_free_trial_eligibleoptional
null
largest_public_bc_idoptional
null
subscriber_countrequired
null
fan_consideration_page_revamp_eligiblityrequired
null
has_anonymous_profile_picturerequired
boolean
hd_profile_pic_url_infooptional
object
heightrequired
integer
urlrequired
string
widthrequired
integer
hd_profile_pic_versionsoptional
array
Array items
object
heightrequired
integer
urlrequired
string
widthrequired
integer
is_verifiedrequired
boolean
profile_pic_idrequired
string
profile_pic_urlrequired
string
transparency_product_enabledrequired
boolean
is_embeds_disabledoptional
boolean
eligible_for_text_app_activation_badgeoptional
boolean
__typenameoptional
string
ownerrequired
object
fbid_v2required
string
feed_post_reshare_disabledrequired
boolean
full_namerequired
string
idrequired
string
is_privaterequired
boolean
is_unpublishedrequired
boolean
pkrequired
string
pk_idoptional
string
show_account_transparency_detailsrequired
boolean
strong_id__required
string
third_party_downloads_enabledrequired
integer
usernamerequired
string
account_typerequired
integer
can_see_quiet_post_attributionoptional
boolean
account_badgesoptional
array
fan_club_inforequired
object
autosave_to_exclusive_highlightrequired
null
connected_member_countrequired
null
fan_club_idrequired
null
fan_club_namerequired
null
has_created_sscoptional
null
has_enough_subscribers_for_sscrequired
null
is_fan_club_gifting_eligiblerequired
null
is_fan_club_referral_eligiblerequired
null
is_free_trial_eligibleoptional
null
largest_public_bc_idoptional
null
subscriber_countrequired
null
fan_consideration_page_revamp_eligiblityrequired
null
has_anonymous_profile_picturerequired
boolean
hd_profile_pic_url_infooptional
object
heightrequired
integer
urlrequired
string
widthrequired
integer
hd_profile_pic_versionsoptional
array
Array items
object
heightrequired
integer
urlrequired
string
widthrequired
integer
is_verifiedrequired
boolean
profile_pic_idrequired
string
profile_pic_urlrequired
string
transparency_product_enabledrequired
boolean
is_embeds_disabledoptional
boolean
eligible_for_text_app_activation_badgeoptional
boolean
__typenameoptional
string
image_versions2required
object
candidatesrequired
array
Array items
object
widthrequired
integer
heightrequired
integer
urlrequired
string
additional_candidatesrequired
object
igtv_first_framerequired
object
widthrequired
integer
heightrequired
integer
urlrequired
string
first_framerequired
object
widthrequired
integer
heightrequired
integer
urlrequired
string
smart_frameoptional
null
scrubber_spritesheet_info_candidatesrequired
object
defaultrequired
object
video_lengthrequired
number
thumbnail_widthrequired
integer
thumbnail_heightrequired
integer
thumbnail_durationrequired
number
sprite_urlsoptional
array
Array items
string
thumbnails_per_rowrequired
integer
total_thumbnail_num_per_spriterequired
integer
max_thumbnails_per_spriterequired
integer
sprite_widthrequired
integer
sprite_heightrequired
integer
rendered_widthrequired
integer
file_size_kbrequired
integer
original_widthoptional
integer
original_heightoptional
integer
is_artist_pickoptional
boolean
media_reposter_bottomsheet_enabledoptional
boolean
enable_media_notes_productionoptional
boolean
product_typerequired
string
is_paid_partnershiprequired
boolean
music_metadatarequired
object
music_inforequired
null
original_sound_inforequired
null
organic_tracking_tokenoptional
string
is_third_party_downloads_eligibleoptional
boolean
ig_media_sharing_disabledoptional
boolean
are_remixes_crosspostableoptional
boolean
boost_unavailable_identifieroptional
null
boost_unavailable_reasonoptional
null
boost_unavailable_reason_v2optional
array
subscribe_cta_visibleoptional
boolean
is_cutout_sticker_allowedoptional
boolean
cutout_sticker_infooptional
array
gen_ai_detection_methodoptional
object
detection_methodrequired
string
fb_aggregated_like_countoptional
integer
fb_aggregated_comment_countoptional
integer
has_high_risk_gen_ai_inform_treatmentoptional
boolean
open_carousel_show_follow_buttonoptional
boolean
is_tagged_media_shared_to_viewer_profile_gridoptional
boolean
should_show_author_pog_for_tagged_media_shared_to_profile_gridoptional
boolean
is_eligible_for_media_note_recs_nuxoptional
boolean
is_social_ufi_disabledoptional
boolean
is_eligible_for_meta_ai_shareoptional
boolean
meta_ai_suggested_promptsoptional
array
can_replyoptional
boolean
floating_context_itemsoptional
array
is_eligible_content_for_post_roll_adoptional
boolean
is_open_to_public_submissionoptional
boolean
can_view_more_preview_commentsoptional
boolean
preview_commentsoptional
array
comment_countrequired
integer
hide_view_all_comment_entrypointoptional
boolean
inline_composer_display_conditionoptional
string
is_comments_gif_composer_enabledoptional
boolean
comment_inform_treatmentoptional
object
action_typerequired
null
should_have_inform_treatmentrequired
boolean
textrequired
string
urlrequired
null
has_likedoptional
boolean
like_countrequired
integer
video_sticker_localesrequired
array
Array items
string
is_dash_eligibleoptional
integer
number_of_qualitiesoptional
integer
video_versionsrequired
array
Array items
object
bandwidthoptional
null
heightrequired
integer
typerequired
integer
urlrequired
string
widthrequired
integer
video_durationrequired
number
has_audiorequired
boolean
clips_tab_pinned_user_idsoptional
array
clips_metadataoptional
object
breaking_content_infooptional
null
breaking_creator_infooptional
null
clips_creation_entry_pointoptional
string
featured_labeloptional
null
is_public_chat_welcome_videooptional
boolean
is_shared_to_fboptional
boolean
professional_clips_upsell_typeoptional
integer
reels_on_the_rise_infooptional
null
show_tipsoptional
null
achievements_infooptional
object
num_earned_achievementsrequired
null
show_achievementsrequired
boolean
additional_audio_infooptional
object
additional_audio_usernamerequired
null
audio_reattribution_inforequired
object
should_allow_restorerequired
boolean
asset_recommendation_infooptional
null
audio_ranking_infooptional
object
best_audio_cluster_idrequired
string
audio_typeoptional
string
branded_content_tag_infooptional
object
can_add_tagrequired
boolean
challenge_infooptional
null
content_appreciation_infooptional
object
enabledrequired
boolean
entry_point_containerrequired
null
contextual_highlight_infooptional
null
cutout_sticker_infooptional
array
disable_use_in_clips_client_cacheoptional
boolean
external_media_infooptional
null
is_fan_club_promo_videooptional
null
merchandising_pill_infooptional
null
music_canonical_idoptional
string
music_inforequired
null
nux_infooptional
null
original_sound_inforequired
object
allow_creator_to_renameoptional
boolean
audio_asset_idrequired
string
attributed_custom_audio_asset_idoptional
null
can_remix_be_shared_to_fboptional
boolean
can_remix_be_shared_to_fb_expansionoptional
boolean
duration_in_msoptional
integer
formatted_clips_media_countoptional
null
hide_remixingoptional
boolean
ig_artistrequired
object
pkoptional
string
pk_idoptional
string
idrequired
string
usernamerequired
string
full_nameoptional
string
is_privateoptional
boolean
strong_id__optional
string
is_verifiedoptional
boolean
profile_pic_idoptional
string
profile_pic_urloptional
string
is_audio_automatically_attributedoptional
boolean
is_eligible_for_audio_effectsoptional
boolean
is_eligible_for_vinyl_stickeroptional
boolean
is_explicitrequired
boolean
is_original_audio_download_eligibleoptional
boolean
is_reuse_disabledoptional
boolean
is_xpost_from_fboptional
boolean
music_canonical_idoptional
null
oa_owner_is_music_artistoptional
boolean
original_audio_subtypeoptional
string
original_audio_titlerequired
string
original_media_idoptional
string
progressive_download_urloptional
string
should_mute_audiorequired
boolean
time_createdoptional
integer
trend_rankoptional
null
previous_trend_rankoptional
null
overlap_duration_in_msoptional
null
audio_asset_start_time_in_msoptional
null
audio_filter_infosrequired
array
audio_partsoptional
array
audio_parts_by_filteroptional
array
consumption_inforequired
object
display_media_idoptional
null
is_bookmarkedoptional
boolean
is_trending_in_clipsrequired
boolean
should_mute_audio_reasonrequired
string
should_mute_audio_reason_typeoptional
null
xpost_fb_creator_infooptional
null
fb_downstream_use_xpost_metadataoptional
object
downstream_use_xpost_deny_reasonrequired
string
originality_infooptional
null
reusable_text_attribute_stringoptional
string
reusable_text_infooptional
array
Array items
object
idrequired
string
textrequired
string
start_time_msrequired
integer
end_time_msrequired
integer
widthrequired
number
heightrequired
number
offset_xrequired
number
offset_yrequired
number
z_indexrequired
integer
rotation_degreerequired
integer
scalerequired
integer
alignmentrequired
string
colorsrequired
array
Array items
object
countrequired
integer
hex_rgba_colorrequired
string
text_format_typerequired
string
font_sizerequired
number
text_emphasis_moderequired
string
is_animatedrequired
integer
shopping_infooptional
null
show_achievementsoptional
boolean
template_infooptional
null
viewer_interaction_settingsoptional
null
clips_textoptional
array
can_viewer_saveoptional
boolean
can_viewer_reshareoptional
boolean
shop_routing_user_idoptional
null
is_organic_product_tagging_eligibleoptional
boolean
igbio_productoptional
null
product_suggestionsoptional
array
commerce_integrity_review_decisionoptional
string
is_reuse_allowedoptional
boolean
has_more_commentsoptional
boolean
max_num_visible_preview_commentsoptional
integer
explore_hide_commentsoptional
boolean
urlrequired
string
__typenameoptional
string
ai_label_infooptional
object
attribution_label_textrequired
string
carousel_media_countoptional
integer
carousel_mediaoptional
array
Array items
object
__typenamerequired
string
strong_id__required
string
idrequired
string
media_typerequired
integer
image_versions2required
object
candidatesrequired
array
Array items
object
widthrequired
integer
heightrequired
integer
urlrequired
string
original_widthrequired
integer
original_heightrequired
integer
carousel_parent_idrequired
string
usertagsrequired
object
inrequired
array
Array items
object
positionrequired
array
Array items
schema
anyOf
number
anyOf
integer
userrequired
object
strong_id__required
string
idrequired
string
full_namerequired
string
is_privaterequired
boolean
is_verifiedrequired
boolean
profile_pic_idrequired
string
profile_pic_urlrequired
string
usernamerequired
string
pkrequired
string
has_audiorequired
boolean
number_of_qualitiesrequired
integer
video_dash_manifestrequired
string
video_versionsrequired
array
Array items
object
urlrequired
string
typerequired
integer
taken_atrequired
integer
accessibility_captionrequired
null
pkrequired
string
coderequired
string
display_urirequired
string
video_dash_manifestoptional
string
accessibility_captionoptional
null
locationoptional
null
video_urloptional
string
next_max_idrequired
string
userrequired
object
pkrequired
string
pk_idoptional
string
usernamerequired
string
full_namerequired
string
is_privaterequired
boolean
is_active_on_text_post_appoptional
boolean
strong_id__required
string
profile_grid_display_typerequired
string
idrequired
string
is_verifiedrequired
boolean
profile_pic_idrequired
string
profile_pic_urlrequired
string
follower_countoptional
integer
fbid_v2optional
string
is_cannesoptional
boolean
auto_load_more_enabledoptional
boolean
statusoptional
string