Instagram

📘
Datastreamer selects from available providers automatically based on your Job configuration. You do not need to manage provider accounts or credentials to use this source.

API data_source: instagram_auto

Configuring a Job

The query type decides how an Instagram Job searches: across the whole platform, by hashtag, or from one account. Each Job uses one query type, set in query.query_type (the Query Type field on the Portal's New Job form), with query.platform set to instagram. To cover more than one, create a Job for each.

Search by topic. keyword finds posts that mention your terms anywhere on Instagram.
Search by hashtag. hashtag finds posts tagged with one hashtag.
Follow an account. user collects posts from one account.
Full control. advanced takes a Lucene query, so you can combine terms and search specific fields. See Advanced Search Query.

Query types

Query Type (Portal)	`query_type`	Fields	Notes
Posts by keyword	`keyword`	`query`	Keyword to search for in posts.
Posts by hashtag	`hashtag`	`query`	The hashtag, without the `#`. Example: `cat`.
Posts by user	`user`	`query`	The Instagram user ID. Example: `starbucks`.
Advanced Search Query	`advanced`	`query`	Lucene query over unified schema fields. See Advanced Search Query.

The query object for each type:

{"platform": "instagram", "query_type": "keyword", "query": "electric vehicles"}
{"platform": "instagram", "query_type": "hashtag", "query": "technology"}
{"platform": "instagram", "query_type": "user", "query": "starbucks"}
{"platform": "instagram", "query_type": "advanced", "query": "(electric OR hybrid) AND vehicle"}

Job options

Field	Description
`query.prioritization`	`freshness` favors newer documents; `coverage` favors collecting a greater volume. See Freshness or Coverage.
`job_type`	`onetime` runs once over a date range; `periodic` runs on a schedule.
`query_from`, `query_to`	One-time Jobs only. Optional start and end of the date range, in ISO 8601 format.
`max_documents`	Optional. Maximum documents to return. This is a soft limit: because pipelines are asynchronous, a few more documents may be returned.
`query.include[].max_documents`	Optional. Collects comments with each post, up to this many per post (a soft limit). Example: `"include": [{ "max_documents": 10 }]`.
`query.max_excess_documents`	Optional. When filtering by date, the maximum number of documents outside the date range to process before stopping. A cost control: retrieved documents are billed even when they are discarded.
`label`, `tags`	Optional. A label for grouping Jobs, and tags for filtering.

Advanced Search Query

The advanced query type takes a Lucene query in query.query. You can search any field in the Datastreamer unified schema; a term without a field searches content.body.

{ "platform": "instagram", "query_type": "advanced", "query": "(\"electric vehicle\" OR ev) AND content.hashtags:charging" }

Do not put dates in the query. Set the date range with query_from and query_to on the Job instead.

See the Schema Reference for field names.

Example Job request

curl --request POST \
  --url 'https://api.platform.datastreamer.io/api/pipelines/{PIPELINE_ID}/components/{COMPONENT_ID}/jobs?ready=true' \
  --header 'apikey: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "job_name": "instagram-example",
  "component_name": "instagram-auto",
  "query": {
    "platform": "instagram",
    "query_type": "hashtag",
    "query": "technology",
    "prioritization": "coverage",
    "include": [
      {
        "max_documents": 10
      }
    ]
  },
  "data_source": "instagram_auto",
  "job_type": "onetime",
  "query_from": "2026-10-01T00:00:00Z",
  "query_to": "2026-10-02T00:00:00Z",
  "max_documents": 1000
}'

Refer to the Job creation documentation for full configuration details: Creating Jobs

API Reference: Create a Job

What is Collected

Each document returned from the Instagram source represents a post or reel. Fields are mapped to the Datastreamer unified schema and include content text, media references, author metadata, engagement metrics (likes, comments), and post date.

Platform-specific fields are available under the instagram schema namespace. See the Schema Reference for field details.

Troubleshooting

Job fails or returns no data

Check that the query, hashtag, or account target is valid and publicly accessible
Verify the date range contains data
Review Job logs for specific errors

Unexpectedly high document counts

Add more specific filters to narrow the query
Set a document limit on the Job to cap volume per run
Review the DVU pricing page to understand how document counts affect costs

Provider switch noted in Job logs

This is expected behavior. If a provider is unavailable, the Job is routed to an alternative automatically. No action is required.

Sources Overview
Creating Jobs
Data Volume Units
Direct Integrations: use if you need a specific provider directly

Configuring a Job

Query types

Job options

Advanced Search Query

Example Job request

What is Collected

Troubleshooting

Related