{"openapi":"3.1.0","info":{"title":"Fanpage Karma Data API","description":"Data API for social media profile data with Bearer token authentication.","version":"v2"},"servers":[{"url":"/api/v2","description":"API v2 base path"}],"tags":[{"name":"Profiles","description":"List and manage profiles accessible with your API token."},{"name":"Token","description":"Validate your API token."},{"name":"Network Data","description":"Retrieve profile metrics, posts and stories for a social media network."}],"paths":{"/{network}":{"get":{"tags":["Network Data"],"summary":"Get network info","description":"Returns usage hints for the given network.","operationId":"getNetworkInfo","parameters":[{"name":"network","in":"path","description":"Social network identifier.","required":true,"schema":{"type":"string","enum":["facebook","instagram","pinterest","youtube","linkedin","tiktok","threads","bluesky","x"]},"example":"facebook"}],"responses":{"400":{"description":"Invalid endpoint — use /{network}/{profileId}/{endpoint}.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"}}}}}}},"/{network}/{profileId}/{endpoint}":{"get":{"tags":["Network Data"],"summary":"Get data for a profile endpoint","description":"Returns metric data (profile), posts or stories for the given network profile. Use the dedicated /{network}/{profileId}/profile/daily endpoint for daily time series. Requires a valid Bearer token. Public demo profiles can be accessed without authentication.","operationId":"getEndpointForProfile","parameters":[{"name":"network","in":"path","description":"Social network identifier.","required":true,"schema":{"type":"string","enum":["facebook","instagram","pinterest","youtube","linkedin","tiktok","threads","bluesky","x"]},"example":"facebook"},{"name":"profileId","in":"path","description":"Network-specific profile ID or username.","required":true,"schema":{"type":"string"},"example":6815841748},{"name":"endpoint","in":"path","description":"Data endpoint to query.","required":true,"schema":{"type":"string","enum":["profile","posts","stories"]},"example":"profile"},{"name":"from","in":"query","description":"Start date (inclusive) in YYYY-MM-DD format.","required":false,"schema":{"type":"string"},"example":"2026-01-01"},{"name":"to","in":"query","description":"End date (inclusive) in YYYY-MM-DD format. Defaults to yesterday (UTC) when only `from` is set.","required":false,"schema":{"type":"string"},"example":"2026-01-31"},{"name":"limit","in":"query","description":"Maximum number of items to return (posts/stories only). Default and max: 1000.","required":false,"schema":{"type":"integer","format":"int32"},"example":50},{"name":"offset","in":"query","description":"Number of items to skip (posts/stories only). Default: 0.","required":false,"schema":{"type":"integer","format":"int32"},"example":0},{"name":"metrics","in":"query","description":"Comma-separated list of metric API names to include. Optional for all endpoints (returns all metrics if omitted). Use the /{network}/{endpoint}/metrics endpoint to discover available metric keys.","required":false,"schema":{"type":"string"},"example":"page_follower,engagement"}],"responses":{"200":{"description":"Data returned successfully.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"},"examples":{"Profile metrics":{"description":"Profile endpoint response with metric data.","value":{"data":{"fans_count":{"title":"Number of Fans","description":"Total number of fans/followers.","value":5.42E7,"formatted_value":"54.2M"},"engagement":{"title":"Engagement","description":"Average engagement rate.","value":0.0012,"formatted_value":"0.12%"}},"metadata":{"version":"v2","network":"facebook","profile_id":"6815841748","profile_name":"Barack Obama","username":"barackobama","endpoint":"profile","date_from":"2026-01-01","date_to":"2026-01-31"}}},"Posts with pagination":{"description":"Posts endpoint response with pagination metadata.","value":{"data":{"posts":[{"id":"6815841748_123456","date":"2026-01-15T14:30:00Z","message":"Hello world!","link":"https://www.facebook.com/6815841748/posts/123456","type":"PHOTO","metrics":{"reactions":{"title":"Reactions","value":1500.0,"formatted_value":"1.5k"}}}]},"metadata":{"version":"v2","network":"facebook","profile_id":"6815841748","endpoint":"posts","date_from":"2026-01-01","date_to":"2026-01-31","total_count":42,"limit":10,"offset":0}}}}}}},"400":{"description":"Invalid request (bad profile ID, endpoint or date range).","content":{"*/*":{"examples":{"Invalid profile ID":{"description":"Invalid profile ID","value":{"data":{},"metadata":{"version":"v2","network":"facebook","profile_id":"invalid","endpoint":"profile"},"error":{"code":"INVALID_PROFILE_ID","message":"Invalid profile ID."}}}}}}},"401":{"description":"Missing or invalid authentication token.","content":{"*/*":{"examples":{"No token":{"description":"No token","value":{"data":{},"metadata":{"version":"v2","network":"facebook"},"error":{"code":"NO_BEARER_TOKEN","message":"No API token given. Use Authorization: Bearer <token>."}}}}}}},"403":{"description":"Token invalid, account suspended, account pending manual review (ACCOUNT_PENDING_REVIEW: new paid accounts are limited to 50 distinct profiles until manually approved by Fanpage Karma) or endpoint not available for network.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"}}}},"429":{"description":"Rate limit or access limit exceeded.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"}}}}},"security":[{"bearerAuth":[]}]}},"/{network}/{profileId}/profile/daily":{"get":{"tags":["Network Data"],"summary":"Get daily time series for a profile","description":"Returns daily time series data for the given network profile. Requires 'from', 'to' and 'metrics' parameters. Requires a valid Bearer token. Public demo profiles can be accessed without authentication.","operationId":"getProfileDaily","parameters":[{"name":"network","in":"path","description":"Social network identifier.","required":true,"schema":{"type":"string","enum":["facebook","instagram","pinterest","youtube","linkedin","tiktok","threads","bluesky","x"]},"example":"facebook"},{"name":"profileId","in":"path","description":"Network-specific profile ID or username.","required":true,"schema":{"type":"string"},"example":6815841748},{"name":"from","in":"query","description":"Start date (inclusive) in YYYY-MM-DD format.","required":false,"schema":{"type":"string"},"example":"2026-01-01"},{"name":"to","in":"query","description":"End date (inclusive) in YYYY-MM-DD format. Defaults to yesterday (UTC) when only `from` is set.","required":false,"schema":{"type":"string"},"example":"2026-01-31"},{"name":"metrics","in":"query","description":"Comma-separated list of metric API names to include. Required. Use the /{network}/profile/metrics endpoint to discover available metric keys.","required":false,"schema":{"type":"string"},"example":"page_follower,engagement"}],"responses":{"200":{"description":"Data returned successfully.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"},"examples":{"Daily time series":{"description":"Daily endpoint response with daily metric values.","value":{"data":{"daily":{"page_follower":{"title":"Number of Fans","values":[{"date":"2026-01-01","value":5.418E7},{"date":"2026-01-02","value":5.4195E7}]},"engagement":{"title":"Engagement","values":[{"date":"2026-01-01","value":0.0011},{"date":"2026-01-02","value":0.0013}]}}},"metadata":{"version":"v2","network":"facebook","profile_id":"6815841748","profile_name":"Barack Obama","endpoint":"profile/daily","date_from":"2026-01-01","date_to":"2026-01-31","metrics":["page_follower","engagement"]}}}}}}},"400":{"description":"Invalid request (bad profile ID or date range).","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"}}}},"401":{"description":"Missing or invalid authentication token.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"}}}},"403":{"description":"Token invalid, account suspended, account pending manual review (ACCOUNT_PENDING_REVIEW: new paid accounts are limited to 50 distinct profiles until manually approved by Fanpage Karma) or endpoint not available for network.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"}}}},"429":{"description":"Rate limit or access limit exceeded.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"}}}}},"security":[{"bearerAuth":[]}]}},"/{network}/{endpoint}/metrics":{"get":{"tags":["Network Data"],"summary":"List available metrics","description":"Returns the list of available metric keys, labels and types for a given network and endpoint type. No authentication required.","operationId":"getMetricsForEndpoint","parameters":[{"name":"network","in":"path","description":"Social network identifier.","required":true,"schema":{"type":"string","enum":["facebook","instagram","pinterest","youtube","linkedin","tiktok","threads","bluesky","x"]},"example":"facebook"},{"name":"endpoint","in":"path","description":"Endpoint type.","required":true,"schema":{"type":"string","enum":["profile","posts","stories"]},"example":"profile"}],"responses":{"200":{"description":"Metrics catalog returned successfully.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"}}}}}}},"/{network}/profile/daily/metrics":{"get":{"tags":["Network Data"],"summary":"List available metrics for profile/daily","description":"Returns the list of available metric keys for the daily time series endpoint. Same metrics as /profile. No authentication required.","operationId":"getMetricsForProfileDaily","parameters":[{"name":"network","in":"path","description":"Social network identifier.","required":true,"schema":{"type":"string","enum":["facebook","instagram","pinterest","youtube","linkedin","tiktok","threads","bluesky","x"]},"example":"facebook"}],"responses":{"200":{"description":"Metrics catalog returned successfully.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"}}}}}}},"/token/validate":{"get":{"tags":["Token"],"summary":"Validate token","description":"Lightweight endpoint to check whether the provided API token is valid. Does not load any profile data. Useful for connectivity checks and token validation.","operationId":"validateToken","responses":{"200":{"description":"Token is valid.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"},"examples":{"Valid token":{"description":"Valid token","value":{"data":{"valid":true},"metadata":{"version":"v2","endpoint":"token/validate"}}}}}}},"401":{"description":"Missing or invalid authentication token.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"}}}},"403":{"description":"Token invalid or account suspended.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"}}}}},"security":[{"bearerAuth":[]}]}},"/profiles/queried":{"get":{"tags":["Profiles"],"summary":"List queried profiles","description":"Returns profiles that have been queried via the API with the given token in the current billing period.","operationId":"listQueriedProfiles","responses":{"200":{"description":"Queried profile list returned.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"}}}},"401":{"description":"Missing or invalid authentication token.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"}}}},"403":{"description":"Token invalid.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"}}}}},"security":[{"bearerAuth":[]}]}},"/profiles/connected":{"get":{"tags":["Profiles"],"summary":"List connected profiles","description":"Returns all connected profiles associated with the account of the given API token. These are profiles added to your Fanpage Karma dashboard with extended analytics permissions.","operationId":"listConnectedProfiles","responses":{"200":{"description":"Profile list returned.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"},"examples":{"Profile list":{"description":"Profile list","value":{"data":{"profiles":[{"network":"facebook","profile_id":"6815841748","profile_name":"Barack Obama","username":"barackobama"},{"network":"instagram","profile_id":"10206720","profile_name":"Instagram","username":"instagram"}]},"metadata":{"version":"v2","endpoint":"connected","total_profiles":2}}}}}}},"401":{"description":"Missing or invalid authentication token.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"}}}},"403":{"description":"Token invalid.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"}}}}},"security":[{"bearerAuth":[]}]}}},"components":{"schemas":{"ApiV2Error":{"type":"object","description":"Error details returned when a request fails.","properties":{"code":{"type":"string","description":"Machine-readable error code.","example":"INVALID_TOKEN"},"message":{"type":"string","description":"Human-readable error message.","example":"Invalid token."}}},"ApiV2Response":{"type":"object","description":"Standard API v2 response wrapper.","properties":{"data":{"type":"object","additionalProperties":{"type":"object"},"description":"Response payload."},"metadata":{"type":"object","additionalProperties":{"type":"object"},"description":"Request metadata such as version, network, profile_id, endpoint, date_from, date_to."},"error":{"$ref":"#/components/schemas/ApiV2Error","description":"Error details. Present only when the request failed."},"message":{"$ref":"#/components/schemas/ApiV2Response","writeOnly":true}}}},"securitySchemes":{"bearerAuth":{"type":"http","description":"Enter your API token (without the 'Bearer ' prefix).","scheme":"bearer"}}}}