Facebook

📘
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: facebook_auto

Configuring a Job

The query type decides how a Facebook Job searches: across the whole platform, from one account, or inside one community. 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 facebook. To cover more than one, create a Job for each.

Search by topic. keyword finds posts that mention your terms anywhere on Facebook.
Follow an account. user collects posts from one account.
Follow a community. group collects posts from one Facebook group.
Search inside a community. group_kw runs a keyword search inside one group, so you get only the group's posts that match.

Query types

Query Type (Portal)	`query_type`	Fields	Notes
Posts by keyword	`keyword`	`query`	Keyword to search for in posts.
Posts by user	`user`	`query`	The Facebook user ID. Example: `starbucks`.
Posts by group	`group`	`group`	The numeric Facebook group ID, for example `123456789`. Copy it from the group URL. Public groups only.
Posts by group/keyword	`group_kw`	`group`, `query`	Keyword search within one group. `group` is the numeric group ID.

The query object for each type:

{"platform": "facebook", "query_type": "keyword", "query": "electric vehicles"}
{"platform": "facebook", "query_type": "user", "query": "starbucks"}
{"platform": "facebook", "query_type": "group", "group": "123456789"}
{"platform": "facebook", "query_type": "group_kw", "group": "123456789", "query": "electric vehicles"}

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. Start and end of the date range, in ISO 8601 format. Both are required.
`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.

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": "facebook-example",
  "component_name": "facebook-auto",
  "query": {
    "platform": "facebook",
    "query_type": "group_kw",
    "group": "123456789",
    "query": "electric vehicles",
    "prioritization": "coverage",
    "include": [
      {
        "max_documents": 10
      }
    ]
  },
  "data_source": "facebook_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 Facebook source represents a post or comment. Fields are mapped to the Datastreamer unified schema and include content text, author metadata, engagement metrics (reactions, comments, shares), and post date.

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

Troubleshooting

Job fails or returns no data

Check that the query 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

Example Job request

What is Collected

Troubleshooting

Related