Dataclawd Instagram Data Collector

A reliable Actor that collects Instagram data through the Dataclawd API — a managed social-data API with API-key authentication, usage reporting and prepaid credits. This Actor is a thin client: it calls the endpoint you choose (or maps a friendly task to the right endpoint automatically), follows pagination (endCursor / maxId) automatically, extracts each item, and writes one row per item into the default Dataset (each successful row is also the pay-per-event billing event).

It covers 36 endpoints: user info/profile/posts/reels/followers/following, post detail/comments/likers/download & video links, hashtag info/recent/top, search (users/hashtags/places/combined), explore sections, location feeds & city directories, music info, and media/user ID conversion.

Powered by Dataclawd API · Not affiliated with Instagram / Meta, Inc.

Quick start

1. Open the Actor's Input tab.
2. Pick a task (collection task), e.g. userPosts — the endpoint is selected automatically.
3. Fill userId (numeric Instagram user ID — use the idUserId endpoint to convert a username to an ID, e.g. instagram → 25025320).
4. Optionally set count (items per page), maxItems / maxPages to control volume, or add multiple objects to targets to batch-collect several users.
5. Click Run and open the Dataset tab when it finishes — every collected item is one row with the raw JSON in the data field.

Input

Field	Type	Default	Description
task	enum	—	Recommended. Collection intent, auto-maps to an endpoint (see Tasks below). Leave empty only if you set endpoint explicitly.
endpoint	enum	auto	Advanced. auto = resolve from task; or set an explicit endpoint to override.
userId	string	—	Instagram numeric user ID. Needed by user* list endpoints (posts/reels/followers/...).
username	string	—	Instagram username without @ (e.g. instagram). Used by profile / ID-conversion endpoints.
shortcode	string	—	Post/reel shortcode (the part after /p/ or /reel/ in a post URL), e.g. C4PYiJQubeR. Needed by post* endpoints.
url	string	—	Full post/reel URL (alternative to shortcode).
q	string	—	Search keyword. Needed by hashtag* / search* endpoints.
type	enum	blended	Search type: blended / users / hashtags / places.
count	integer	12	Items per page (IG commonly uses 12 / 30).
locationPk	string	—	Instagram location ID. Needed by location* endpoints.
lat / lng	string	—	Coordinates for directory* endpoints.
tab	enum	ranked	Location posts tab: ranked (top) / recent.
countryCode / cityId / page	string/int	—	Directory endpoints (directoryCities / directoryLocations).
musicId	string	—	Music ID. Needed by musicInfo.
sectionId	string	—	Explore section ID (optional for explore*).
maxId	string	(empty)	Start cursor for search/hashtag/explore/music endpoints.
targets	array of object	(empty)	Batch mode: each element is a param set, collected one after another.
proxyUrl	string	(empty)	Proxy used by Dataclawd's server when fetching Instagram.
httpMethod	enum	GET	Dataclawd Instagram endpoints are GET-only; POST usually returns endpoint_not_found.
maxItems	integer	100	Stop after this many items in total (max 100 000).
maxPages	integer	10	Max pages per target (max 100).
startCursor	string	(empty)	Start from a previous cursor (endCursor / maxId).
itemsPath	string	(empty)	Dot-path to the item list. Leave empty for auto-detection (largest array).
nextCursorPath	string	(empty)	Dot-path to the next-page cursor. Leave empty for auto-detection (end_cursor / max_id / profile_grid_items_cursor ...).
paginationParam	enum	auto	Query param used for paging: auto (per endpoint), endCursor, maxId, or none.

Endpoints

Tasks

Pick a task and the Actor selects the endpoint for you. Fill the params below (username / userId / shortcode / q …).

Task	Endpoint	Required params
userInfo User info	userInfo	username or userId
userPosts User posts	userPosts	userId
userReels User Reels	userReels	userId
userFollowers User followers	userFollowers	userId
userFollowing User following	userFollowing	userId
postDetail Post details	postDetail	shortcode or url
postComments Post comments	postComments	shortcode or url
postLikers Post likers	postLikers	shortcode or url
hashtagTop Hashtag top	hashtagTop	q
hashtagRecent Hashtag recent	hashtagRecent	q
search General search	search	q
searchUsers Search users	searchUsers	q
searchPlaces Search places	searchPlaces	q
locationFeeds Location posts	locationFeeds	locationPk
explore Explore page	exploreSection	—

ID conversion — idUserId, idUsername, idMediaId, idMediaShortcode User — userInfo, userProfile, userProfile2, userWebProfile, userPosts, userPosts2, userReels, userTagged, userReposts, userRelatedProfiles, userFollowers, userFollowing Post — postDetail, postComments, postTopComments, postLikers, postDownloadLink, postVideoUrl Hashtag — hashtagInfo, hashtagRecent, hashtagTop Search — search, searchUsers, searchHashtags, searchPlaces Explore — exploreSection, exploreSections Location / directory — locationFeeds, locationInfo2, directoryCities, directoryLocations Music — musicInfo

Output (Dataset — one row per collected item)

Field	Description
platform	Always instagram.
endpoint	The endpoint that produced this row.
status	completed (data collected) or failed (request-level failure).
target	Human-readable target summary, e.g. userId=25025320.
page	Page number this item came from (1-based).
itemIndex	Sequential index within the run (1-based).
cursor	Cursor used to fetch that page (-1 = first page).
data	The collected item — the raw JSON returned by Dataclawd (an IG media / user / comment object).
errorStage	Where a failure happened: connect_failed / server_error / auth_error / rate_limited / request_error / parse_error / empty_result.
errorCode	HTTP status code (if any), e.g. 429.
error	Error message on failed rows.

Note: some Instagram endpoints require Dataclawd's own Instagram session to be logged in. If Dataclawd's backend is logged out / rate-limited, the API returns login_required / "Please wait a few minutes" style payloads; the Actor writes them as failed rows with the original message in error (best-effort collection still works for endpoints that are available).

Run status & status message

While running, the Actor's status message is updated periodically (Collecting … → Collecting …: wrote n items → Done: …). The run succeeds (SUCCEEDED) as soon as at least one item is collected. If every target fails or returns nothing, the run ends FAILED with an explanatory message. Billing happens only for completed rows.

How to verify the results

1. Run status: the run is SUCCEEDED when at least one item was written; the status message shows live progress.
2. Per-item state: open the run's Dataset — every collected item has status=completed with the raw JSON in data; failed rows explain why (errorStage / errorCode / error).
3. Spot-check against the API: re-run one target in the Dataclawd API Console and compare with the row's data.
4. Billing: only completed rows carry the item-collected pay-per-event charge.

Developer note: for automated checks (run status, row schema, optional Dataclawd API replay), use python3 tools/verify_output.py --run <RUN_ID> [--api].

Pricing

Pay-per-event (PPE): one item-collected event per successfully collected item. Failed rows do not carry this event.

Publishing note: define an item-collected event with your price in the Actor's Monetization tab. The platform's built-in synthetic event apify-default-dataset-item is charged automatically per default-dataset item when PPE is enabled; set its price to 0 if you don't want a per-item base fee.

Configuration (publisher)

The following environment variables are configured on the Actor's version settings and are not visible to end users:

• DATACLAWD_API_HOST — Dataclawd API base URL (e.g. https://api.dataclawd.example).
• DATACLAWD_API_KEY — Dataclawd API key (sent as X-API-Key).

Disclaimer

This Actor is not affiliated with, endorsed by, or sponsored by Instagram or Meta, Inc. Collect only data you are authorized to collect, and comply with Instagram's Terms of Service, the Dataclawd service terms, and applicable law.

---