Instagram Profile Analysis API
Base URL: https://viveka.darkgravitylabs.com
Authentication: None required (for now)
How it works: Viveka pulls photos and videos from Instagram profiles and sends them to Gemini AI for analysis. The AI can understand both images and video content, analyzing visual themes, captions, and more based on your prompt.
Sync vs Async: /api/v1/analyze gives results right away.
/api/v1/jobs lets you start a job and check back later.
Synchronous: Waits for analysis to complete before returning results (60-120 seconds).
| Parameter | Type | Required | Description |
|---|---|---|---|
profiles |
array[string] | Yes | Instagram usernames (currently max 1 profile) |
prompt |
string | Yes | Analysis question for the AI |
max_posts_per_profile |
integer | No | Posts to analyze (default: 20, max: 100) |
curl -X POST https://viveka.darkgravitylabs.com/api/v1/analyze \
-H "Content-Type: application/json" \
-d '{
"profiles": ["natgeo"],
"prompt": "What are the main themes?",
"max_posts_per_profile": 15
}'
{
"results": [
{
"username": "natgeo",
"status": "success",
"analysis": "# Analysis\n\nMain themes include...",
"error_code": null,
"error_message": null
}
]
}
Asynchronous: Returns immediately with job_id. Poll for results using GET
endpoint below.
| Parameter | Type | Required | Description |
|---|---|---|---|
profiles |
array[string] | Yes | Instagram usernames (currently 1 profile) |
prompt |
string | Yes | Analysis question for the AI |
max_posts_per_profile |
integer | No | Posts to analyze (default: 20, max: 100) |
curl -X POST https://viveka.darkgravitylabs.com/api/v1/jobs \
-H "Content-Type: application/json" \
-d '{
"profiles": ["natgeo"],
"prompt": "What are the main themes?",
"max_posts_per_profile": 15
}'
{
"job_id": "550e8400-e29b-41d4-a716-446655440000"
}
Check job status and retrieve results.
| Parameter | Type | Required | Description |
|---|---|---|---|
job_id |
string (UUID) | Yes | Job ID from POST /api/v1/jobs response |
curl https://viveka.darkgravitylabs.com/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000
completed){
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"created_at": "2025-01-15T10:30:00Z",
"results": [
{
"username": "natgeo",
"status": "success",
"analysis": "# Analysis\n\n...",
"error_code": null,
"error_message": null
}
],
"error": null
}
Status values: pending, running, completed,
failed
When analysis fails, results include an error code and message:
| Code | Description |
|---|---|
PROFILE_NOT_FOUND |
Instagram profile doesn't exist |
PRIVATE_PROFILE |
Profile is private |
INVALID_USERNAME |
Invalid username format |
CONTENT_BLOCKED |
Blocked by safety filters |
EMPTY_ANALYSIS |
AI returned empty analysis |
APIFY_ERROR |
Failed to fetch profile data |
GEMINI_ERROR |
AI analysis service error |
NOT_IMPLEMENTED |
Feature not yet implemented |
UNKNOWN_ERROR |
Unexpected error occurred |
{
"results": [
{
"username": "invalid_user",
"status": "error",
"analysis": null,
"error_code": "PROFILE_NOT_FOUND",
"error_message": "This Instagram profile doesn't exist"
}
]
}
curl -X POST https://viveka.darkgravitylabs.com/api/v1/analyze \
-H "Content-Type: application/json" \
-d '{
"profiles": ["natgeo"],
"prompt": "Analyze the visual storytelling style",
"max_posts_per_profile": 20
}' | jq '.results[0].analysis'
JOB_ID=$(curl -s -X POST https://viveka.darkgravitylabs.com/api/v1/jobs \
-H "Content-Type: application/json" \
-d '{
"profiles": ["natgeo"],
"prompt": "Analyze the visual storytelling style",
"max_posts_per_profile": 20
}' | jq -r '.job_id')
echo "Job ID: $JOB_ID"
while true; do STATUS=$(curl -s https://viveka.darkgravitylabs.com/api/v1/jobs/$JOB_ID | jq -r '.status') echo "Status: $STATUS" [[ "$STATUS" == "completed" || "$STATUS" == "failed" ]] && break sleep 5 done
curl -s https://viveka.darkgravitylabs.com/api/v1/jobs/$JOB_ID | jq '.results[0].analysis'
Be a founding user. I'm building what you need. Hear about new features.
Be a founding user. I'm building what you need. Hear about new features.
