Data Formats & Field Types

Understanding data formats ensures you correctly parse and use API responses. This guide covers all field types, formats, and data structures used throughout the Influship API.

Core Data Types

Creator ID

Unique identifier for a creator (person-level).

creator_id

string

Format: UUID v4Example: 123e4567-e89b-12d3-a456-426614174000Usage: Use with /v1/creators endpoint or as creator_profile_id cross-reference

Unique identifier for a platform-specific social account.

Format: UUID v4Example: abc12345-6789-0def-ghij-klmnopqrstuvUsage: Returned in profile data, unique per platform account

Platform

Social media platform identifier.

platform

string

Values: instagram | tiktokExample: "instagram"

Platform Support

Instagram: ✅ Fully supported across all endpoints
TikTok: ✅ Supported on most endpoints
YouTube, Twitter/X: 🔜 Coming soon

Metric Fields

Follower Count

Total number of followers on a platform.

follower_count

integer

Range: 0 to 999,999,999+Example: 125000Nullable: null if account is private or data unavailableNote: Real-time follower counts may vary from cached data

Engagement Rate

Percentage representing how engaged an audience is.

engagement_rate

number

Range: 0.0 to 100.0 (percentage)Example: 4.2 (represents 4.2%)Formula: (avg_likes + avg_comments) / follower_count * 100Calculation Period: Based on recent posts (typically last 12 posts)Nullable: null if insufficient data availableIndustry Benchmarks:

Micro-influencers (10K-100K): 3-7%
Mid-tier (100K-500K): 2-5%
Macro (500K+): 1-3%

Average Metrics

Calculated from recent post performance.

avg_likes_recent

number

Average likes per post from recent contentExample: 5240Period: Last 12 posts

avg_comments_recent

number

Average comments per post from recent contentExample: 450Period: Last 12 postsOnly in: Detailed mode

avg_video_views_recent

number

Average video views for video postsExample: 15000Applies to: Video posts onlyOnly in: Detailed mode

Growth Metrics

follower_change_rate_monthly_approx

number

Approximate monthly follower growth rate as percentageExample: 2.5 (2.5% growth per month)Interpretation:

Positive values: Growing audience
Negative values: Declining audience
Near zero: Stable audience

Only in: Detailed mode

Content Metrics

posts_per_week_recent

number

Average posts published per weekExample: 4.5Period: Last 30 days

media_count

integer

Total number of posts publishedExample: 342Includes: All media types (photos, videos, carousels)Only in: Detailed mode

highlight_reel_count

integer

Number of Instagram Story highlightsExample: 8Platform: Instagram only (null for other platforms)Only in: Detailed mode

Timestamp Fields

All timestamps use ISO 8601 format with UTC timezone.

timestamp

string

Format: YYYY-MM-DDTHH:mm:ss.sssZExample: "2024-01-15T10:30:00.000Z"Timezone: Always UTC (Z suffix)

const timestamp = "2024-01-15T10:30:00.000Z";
const date = new Date(timestamp);
console.log(date.toLocaleString()); // Local time

Common Timestamp Fields

posted_at

string

When content was originally published

scraped_at

string

When we last updated this data (metrics accurate as of this time)

timestamp

string

Generic timestamp field (context-dependent)

Text Fields

Bio & Description Fields

bio

string

Creator or account biography textMax Length: ~500 characters (platform dependent)Example: "Certified personal trainer and wellness coach"Nullable: null if not provided by creator

caption

string

Post caption textMax Length: Varies by platform

Instagram: ~2,200 characters
TikTok: ~2,200 characters

Example: "Morning workout complete! 💪 Ready to take on the day. #fitness"

accessibility_caption

string

Alt text or AI-generated image descriptionExample: "Person doing yoga pose on beach at sunrise"Usage: Screen readers, content analysis

Username & Handle Fields

username

string

Platform-specific username (without @ symbol)Example: "sarah_fitness"Format: Lowercase, alphanumeric, underscores, periods

display_name

string

Platform display name (can include spaces, emoji, etc.)Example: "Sarah | Fitness Coach 💪"

name

string

Creator’s full name (person-level)Example: "Sarah Johnson"

URL Fields

All URLs are returned as absolute, fully-qualified URLs.

avatar_url

string

Profile picture URLExample: "https://cdn.influship.com/avatars/sarah.jpg"Validity: URLs typically valid for 24-48 hoursTip: Cache images to avoid broken links

external_url

string

External website link from profileExample: "https://sarahfitness.com"Nullable: null if creator hasn’t added a link

media_url

string

Primary media file URL (image or video)Example: "https://cdn.influship.com/posts/img_123.jpg"

thumbnail_url

string

Video thumbnail image URLExample: "https://cdn.influship.com/posts/thumb_123.jpg"Condition: Only present when is_video: true

Boolean Fields

verified

boolean

Whether account has platform verification badgeValues: true | falsePlatform Differences:

Instagram: Blue checkmark (official verification)
TikTok: Blue checkmark (official verification)

Example: true

is_video

boolean

Whether post contains video contentValues: true | falseExample: false

is_business_account

boolean

Whether account is set to business/creator modeValues: true | false | nullNullable: null if platform doesn’t expose this data

Pagination Fields

See Pagination Guide for detailed usage.

cursor

string

Opaque pagination cursor (base64-encoded)Example: "eyJpZCI6MjUsInNjb3JlIjowLjg1fQ=="Usage: Pass as cursor query parameter for next pageImportant: Never decode or construct manually

has_more

boolean

Whether additional pages existValues: true | falseLogic:

true → More results available, use cursor to fetch
false → This is the last page

filtered_total

integer

Total matching results before paginationExample: 1247Usage: Display “Showing 1-25 of 1,247 results”Note: This is the total after filters, not the entire database

AI-Generated Fields

AI Recommendation

ai_recommendation

object

AI-powered recommendation with score and explanation

{
  "score": 0.92,
  "explanation": "Strong match for fitness content with high engagement"
}

score

number

Relevance score from 0 to 1Range: 0.0 to 1.0Interpretation:

0.9-1.0: Excellent match
0.7-0.89: Strong match
0.5-0.69: Good match
Below 0.5: Weak match

explanation

string

Human-readable explanation of the recommendationExample: "Strong match for fitness content with high engagement and authentic wellness focus"

AI Analysis

ai_analysis

object

AI-generated content insights (optional feature)

{
  "summary": "Post showcases morning workout routine...",
  "transcript": "Good morning everyone! Today we're doing..."
}

Only present when: features: ["ai_analysis"] requestedCost: +0.5 credits per post

Brand Safety

brand_safety

object

Brand safety analysis with rating and flags

{
  "rating": "A",
  "overall_confidence": 0.92,
  "summary": "Content is family-friendly...",
  "flags": [],
  "reasoning": "Analysis of 20 recent posts...",
  "metadata": {...}
}

Only present when: Brand safety analysis requested

rating

string

Brand safety ratingValues:

"A" - Safe (no significant risks)
"B" - Moderate (minor concerns)
"C" - Risk (significant concerns)

Response Structures

Search Response

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Sarah Fitness",
      "avatar_url": "https://cdn.influship.com/avatars/sarah.jpg",
      "bio": "Certified personal trainer",
      "profiles": [...],
      "ai_recommendation": {
        "score": 0.92,
        "explanation": "Strong match for fitness content"
      }
    }
  ],
  "filtered_total": 247,
  "has_more": true,
  "next_cursor": "eyJpZCI6MjV9"
}

Creator Response

{
  "creators": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Sarah Fitness",
      "bio": "Certified personal trainer and wellness coach",
      "avatar": "https://cdn.influship.com/avatars/sarah.jpg",
      "profiles": [...]  // If include_profiles=true
    }
  ]
}

Profile Response

{
  "profiles": [
    {
      "id": "abc123",
      "creator_profile_id": "123e4567-e89b-12d3-a456-426614174000",
      "platform": "instagram",
      "username": "sarah_fitness",
      "display_name": "Sarah | Fitness Coach",
      "bio": "Transform your body in 12 weeks 💪",
      "follower_count": 125000,
      "engagement_rate": 4.2,
      "verified": true,
      "avatar_url": "https://...",
      "external_url": "https://sarahfitness.com"
    }
  ]
}

Error Response

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": {
      "fields": ["query"],
      "context": "query must be between 1-500 characters"
    },
    "request_id": "req_8a7b9c0d1e2f3g4h"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Field Availability

By Response Mode

Lite Mode
Detailed Mode

Always Available:

Basic profile info (id, username, display_name)
Follower count, engagement rate
Verification status
Avatar and external URLs

Cost: Base pricing only

By Endpoint

Different endpoints return different field combinations:

/v1/search - Search Results

Returns: Creator data + social accounts + AI recommendationUnique Fields: ai_recommendation, filtered_total

/v1/creators - Creator Profiles

Returns: Person-level creator data, optionally with social accountsUnique Fields: Creator name, bio, avatar (person-level)

/v1/profiles - Social Account Lookup

/v1/posts/* - Post Data

Returns: Post content + metrics + optional AI featuresUnique Fields: caption, media_url, likes_count, ai_analysis, brand_safety

Nullable Fields

Many fields can be null. Here’s why and how to handle them:

Why null?

Fields are null when:

Creator hasn’t provided the information
Platform doesn’t expose the data
Account is private
Insufficient data for calculations
Feature not requested (e.g., AI features)

Common Nullable Fields

bio - Creator hasn’t written a bio
external_url - No link in profile
follower_count - Private account
engagement_rate - Not enough posts to calculate
ai_analysis - Feature not requested
thumbnail_url - Post is not a video

Handling null in Code

// JavaScript - Use optional chaining and nullish coalescing
const followers = creator.follower_count ?? 0;
const bio = creator.bio ?? "No bio provided";

// Python - Use get() with default
followers = creator.get('follower_count') or 0
bio = creator.get('bio') or "No bio provided"

Data Freshness

Real-time vs Cached

Data freshness varies by field and endpoint. Understanding this helps set correct expectations.

Real-time Fields

info

Updated with every API request:

Creator existence checks
API metadata (request_id, credits)
Pagination state

Cached Fields (Updated Periodically)

warning

Updated every 24-48 hours:

Follower counts
Engagement metrics
Post counts
Avatar URLs

Check scraped_at timestamp to know when data was last updated

Historical Fields

note

Rarely change after creation:

Post content (caption, media)
Posted timestamps
Creator IDs

Best Practices

Check for null

Always handle nullable fields gracefully with defaults or conditional rendering

Use TypeScript/Types

Leverage type definitions to catch null handling issues at compile time

Cache URLs

Avatar and media URLs expire after 24-48 hours - cache images to avoid broken links

Respect Data Freshness

Check scraped_at timestamps when data recency matters

Parse Timestamps Correctly

Always parse ISO 8601 strings to native date objects in your timezone

Handle Large Numbers

Use appropriate number types for follower counts (can exceed 32-bit integers)

Need Help?

API Reference

Complete endpoint documentation

Code Examples

See data formats in action

Support

Get technical assistance

Overview

Endpoints

​Data Formats & Field Types

​Core Data Types

​Creator ID

​Social Account ID

​Platform

​Metric Fields

​Follower Count

​Engagement Rate

​Average Metrics

​Growth Metrics

​Content Metrics

​Timestamp Fields

​Common Timestamp Fields

​Text Fields

​Bio & Description Fields

​Username & Handle Fields

​URL Fields

​Boolean Fields

​Pagination Fields

​AI-Generated Fields

​AI Recommendation

​AI Analysis

​Brand Safety

​Response Structures

​Search Response

​Creator Response

​Profile Response

​Error Response

​Field Availability

​By Response Mode

​By Endpoint

​Nullable Fields

​Data Freshness

​Real-time vs Cached

​Best Practices

Check for null

Use TypeScript/Types

Cache URLs

Respect Data Freshness

Parse Timestamps Correctly

Handle Large Numbers

​Need Help?

API Reference

Code Examples

Support

Data Formats & Field Types

Core Data Types

Creator ID

Social Account ID

Platform

Metric Fields

Follower Count

Engagement Rate

Average Metrics

Growth Metrics

Content Metrics

Timestamp Fields

Common Timestamp Fields

Text Fields

Bio & Description Fields

Username & Handle Fields

URL Fields

Boolean Fields

Pagination Fields

AI-Generated Fields

AI Recommendation

AI Analysis

Brand Safety

Response Structures

Search Response

Creator Response

Profile Response

Error Response

Field Availability

By Response Mode

By Endpoint

Nullable Fields

Data Freshness

Real-time vs Cached

Best Practices

Need Help?