Content Monitoring

Content monitoring lets you discover and index social media posts and videos into your agent’s knowledge base. Start a one-time scrape or set up ongoing monitoring across TikTok, Instagram, and YouTube. Scraped content trains the agent’s understanding of trends, engagement patterns, and creator activity.

Note

All content monitoring endpoints require authentication via the X-API-Key header and a valid agent_id query parameter. The agent’s workspace must have an active credit purchase.

Accessing scraped data

There is no API to download raw scraped data directly. Instead, query the data through your agent:

• Agent Chat — ask natural language questions like “what are the top performing videos about skincare this week?” via POST /v1/agent/run. The agent analyzes your indexed source data and returns insights.
• Automation Pipelines — set up scheduled prompts that query your data automatically and populate Vidsheet rows with the results. See Pipelines for details.

Both approaches use the same LLM-powered search engine under the hood — your data is analyzed on demand, not exposed as a raw dump.

Platform capabilities

Not all platforms support all search types:

Platform	Username	Hashtag	Keyword
TikTok	Yes	Yes	Yes
Instagram	Yes	Yes	No
YouTube	Yes	Yes	Yes

Pricing

Item	Cost
Per video/post scraped	$0.015
Per comment (when comment monitoring is enabled)	$0.002

Costs are converted to credits using the standard credit formula.

---

Create monitoring job

Starts a social media content scrape or monitoring job. For one-time scrapes, the job transitions to completed after processing. For ongoing monitoring, the job stays in processing and scrapes on a recurring schedule.

POST /v1/user_jobs?agent_id={agent_id}

Parameters

Parameter	Type	Required	Description
agent_id	string	Yes	The agent ID (query parameter).
user_job[user_job_type]	string	Yes	Must be "train_social".
user_job[data]	string (JSON)	Yes	JSON-stringified object containing the monitoring configuration (see Data fields below).

Data fields

The user_job[data] value is a JSON string containing:

Field	Type	Required	Description
platform	string	Yes	Target platform: tiktok, instagram, or youtube.
type	string	Yes	Search type: username, hashtag, or keyword. Must be supported by the chosen platform (see table above).
value	string	Yes	The search value. Usernames must start with @ (e.g. @creator). Hashtags must start with # (e.g. #skincare). Keywords are plain text.
days	integer	No	Filter to content from the last N days. One of: 0 (no filter), 1, 7, 30, 90, 180.
country	string	No	Two-letter country code (e.g. us, gb) to filter by region.
max_results	integer	No	Maximum number of results to fetch per scrape (1–50).
monitoring	boolean	No	false (default) for a one-time scrape that completes after processing. true for ongoing scheduled monitoring.
comment_monitoring	boolean	No	true to also scrape comments (adds per-comment cost). Default false.

Response

{
  "user_job_id": 12345
}

Status flow

Status	Description
pending	Job created, queued for processing.
processing	Scraping in progress. For monitoring jobs, stays here between scrape cycles.
completed	One-time scrape finished (only when monitoring is false).
failed	Scrape failed. Check failed_reason on the job.

Poll status via GET /v1/user_jobs/{id}?agent_id={agent_id}.

Example: Monitor an Instagram account

curl -X POST "https://api.gen.pro/v1/user_jobs?agent_id=your-agent-id" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: multipart/form-data" \
  -F 'user_job[user_job_type]=train_social' \
  -F 'user_job[data]={"platform":"instagram","type":"username","value":"@fashionbrand","days":30,"max_results":50,"monitoring":true}'

Example: One-time YouTube hashtag scrape

curl -X POST "https://api.gen.pro/v1/user_jobs?agent_id=your-agent-id" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: multipart/form-data" \
  -F 'user_job[user_job_type]=train_social' \
  -F 'user_job[data]={"platform":"youtube","type":"hashtag","value":"#cooking","max_results":50,"monitoring":false}'

Example: TikTok keyword search with comments

curl -X POST "https://api.gen.pro/v1/user_jobs?agent_id=your-agent-id" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: multipart/form-data" \
  -F 'user_job[user_job_type]=train_social' \
  -F 'user_job[data]={"platform":"tiktok","type":"keyword","value":"ai tools","days":7,"country":"us","monitoring":true,"comment_monitoring":true}'

Errors

Status	Error code	Description
401	unauthorized	Missing or invalid API key.
403	permission_denied	You do not have access to this agent.
422	validation_error	Invalid platform, type, value format, or unsupported platform/type combination.
422	no_active_credit_purchase	The agent’s workspace has no active credit purchase.

---

Update monitoring job

Updates the configuration of an existing monitoring job. Only jobs with pending or processing status can be updated.

PUT /v1/user_jobs/{id}?agent_id={agent_id}

Parameters

Parameter	Type	Required	Description
id	integer	Yes	The user job ID (path parameter).
agent_id	string	Yes	The agent ID (query parameter).
platform	string	No	Target platform: tiktok, instagram, or youtube.
type	string	No	Search type: username, hashtag, or keyword.
value	string	No	The search value.
days	integer	No	Lookback window. One of: 0, 1, 7, 30, 90, 180.
country	string	No	Two-letter country code.
max_results	integer	No	Maximum results per scrape (1–50).
monitoring	boolean	No	true for ongoing monitoring, false for one-time.
comment_monitoring	boolean	No	true to also scrape comments.

Response

{
  "user_job_id": 12345
}

Example

curl -X PUT "https://api.gen.pro/v1/user_jobs/12345?agent_id=your-agent-id" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: multipart/form-data" \
  -F 'platform=instagram' \
  -F 'type=username' \
  -F 'value=@fashionbrand' \
  -F 'days=7' \
  -F 'max_results=50' \
  -F 'monitoring=true'

Errors

Status	Error code	Description
401	unauthorized	Missing or invalid API key.
403	permission_denied	You do not have access to this agent.
404	user_job_not_found	No monitoring job exists with the given ID for this agent.
422	job_status_invalid	Can only update jobs with pending or processing status.
422	validation_error	Invalid data fields.