{"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"}}}},"429":{"description":"Rate-Limit überschritten (100 Anfragen pro Minute und IP). Der Body kommt vom RateLimitInterceptor und ist deshalb kein ApiError, sondern {\"error\": \"Too many requests\", \"detail\": \"Please try again later\"}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}},"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/dashboards":{"get":{"tags":["Profiles"],"summary":"List dashboard profiles","description":"Returns all profiles contained in the active Analytics dashboards of the account of the given API token, regardless of which user added them. Each profile appears once and lists the dashboards it belongs to. Only profiles from networks supported by this API are included. Listing does not count towards your quota; requesting data for a profile does.","operationId":"listDashboardProfiles","responses":{"200":{"description":"Dashboard profile list returned.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiV2Response"},"examples":{"Dashboard profile list":{"description":"Dashboard profile list","value":{"data":{"profiles":[{"network":"facebook","profile_id":"6815841748","profile_name":"Barack Obama","username":"barackobama","dashboards":[{"id":5629499534213120,"name":"Politics"},{"id":5707702298738688,"name":"Competitors"}]},{"network":"instagram","profile_id":"10206720","profile_name":"Instagram","username":"instagram","dashboards":[{"id":5707702298738688,"name":"Competitors"}]}]},"metadata":{"version":"v2","endpoint":"dashboards","total_profiles":2,"total_dashboards":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":[]}]}},"/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."},"details":{"type":"object","additionalProperties":{"type":"object"},"description":"Machine-readable context for this error, e.g. quota_max and quota_used for an exhausted profile quota, or limit and reset for the hourly rate limit."}}},"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}}},"RateLimitError":{"description":"Antwort bei überschrittenem Rate-Limit (HTTP 429)","properties":{"error":{"type":"string","description":"Fehlerbezeichnung","example":"Too many requests"},"detail":{"type":"string","description":"Hinweis für den Aufrufer","example":"Please try again later"}},"required":["detail","error"]}},"securitySchemes":{"bearerAuth":{"type":"http","description":"Enter your API token (without the 'Bearer ' prefix).","scheme":"bearer"}}}}