# Social Metrics Reconciler: Map and Compare Business Reports (`althorlabs/social-metrics-reconciler`) Actor USD 0.25 per completed report (one per run). Combine mapped CSV/JSON business metrics across up to 20 accounts and 20,000 rows. Customer-supplied data; no platform login. - **URL**: https://apify.com/althorlabs/social-metrics-reconciler.md - **Developed by:** [Althor Labs](https://apify.com/althorlabs) (community) - **Categories:** Social media, Business - **Security:** Limited permissions - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing $0.25 / completed report (one per run) This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ## Social Metrics Reconciler: Map and Compare Business Reports **USD 0.25 per completed report (one per run).** Combine customer-provided business-account CSV or JSON metric reports into a consistent JSON dataset. Map each report's own headers to canonical fields; the Actor returns row records, per-account period summaries, and deltas for compatible windows. This Actor reads only files you provide. It does not sign in to Instagram, TikTok, or other platforms, fetch account URLs, verify a source, or promise compatibility with a platform's native export format. The included sample is synthetic and is not a native export. ### Input Add one report per CSV or JSON file in `reports`. For each report, set `format`, provide CSV text or JSON rows in `data`, and map exact source header names to canonical fields. Required mappings are `business_account_key`, `platform`, `period_start`, and `period_end`. Map at least one metric: `impressions`, `views`, `reach`, `likes`, `comments_count`, `shares`, or `clicks`. `post_key` is optional. Periods use `YYYY-MM-DD`. You may combine multiple business accounts and periods. Use a stable opaque business account key, a platform label, and a stable post key where post-level rows are supplied. Metric counts must be non-negative integers. Blank and missing metrics remain `null`; zero remains zero. Unknown source columns are discarded and do not appear in output. Limits are 5,000,000 UTF-8 bytes for the complete input, 20 business accounts, and 1,000 source rows per business account across all supplied periods. Duplicate account/platform/period/post keys are rejected with a safe error code. Do not include personal profiles, usernames or handles identifying private people, follower lists, comment text, names, email addresses, audience demographics, or contact records. Supply business aggregate counts only. The Actor does not log source records or mapped values. ### Output The complete JSON result is stored in the default key-value store at key `OUTPUT`. The default dataset contains one compact index item with record counts and `result_key: "OUTPUT"`. The output schema links directly to both locations. This stores results larger than Apify's 9 MB per-dataset-item limit without splitting the JSON arrays. The `OUTPUT` record contains: - `canonical_records`: only the allowlisted canonical fields and mapped metric values. - `account_summaries`: account/platform/period totals. Impressions, views, likes, comments, shares, and clicks are summed only when all rows are present. Account-level and post-level rows cannot be mixed in one account period. Post-level reach is never presented as account reach; aggregate reach is available only from a single account-level row. - `period_deltas`: contiguous adjacent periods are compared only within the same account and platform, for equal-length non-overlapping periods and matching metric definition IDs. Gaps, incompatible periods, missing values, or mismatched metric definitions produce an unavailable delta with a reason. Metrics on different platforms remain separate. A platform label is user-supplied metadata, not source verification. By default, a metric definition ID is scoped to the platform and canonical metric name. Set an explicit stable `metric_definition_ids` value when the metric's meaning changes; mismatched IDs prevent a delta. ### Pricing and support USD 0.25 per completed report (one per run). A successful run produces one combined report, covering all supplied accounts and periods within the input limits. The charge is once for that completed report. There is no Actor-start fee; standard Apify platform usage is included. A run that fails before producing its report is not charged. ### Example The prefilled two-period sample uses fabricated business data and two different source header sets. The credential-free Apify SDK 4.1.0 local-storage smoke produced this result summary: ```json { "canonical_record_count": 2, "account_summary_count": 2, "period_delta_count": 1, "sample_impressions_delta": 4, "result_key": "OUTPUT" } ``` It does not establish any Instagram or TikTok native export compatibility. # Actor input Schema ## `reports` (type: `array`): Each report is one CSV text block or a JSON row array with a canonical-to-source header mapping. This field accepts customer-provided files only; it does not fetch URLs or connect to social platforms. ## Actor input object example ```json { "reports": [ { "format": "csv", "data": "acct,network,from,to,post,shown,unique_reach\nbrand-a,instagram,2026-10-01,2026-10-07,p-1,10,7", "mapping": { "business_account_key": "acct", "platform": "network", "period_start": "from", "period_end": "to", "post_key": "post", "impressions": "shown", "reach": "unique_reach" }, "metric_definition_ids": { "impressions": "post_impressions_v1", "reach": "account_reach_v1" } }, { "format": "json", "data": "[{\"business\":\"brand-a\",\"channel\":\"instagram\",\"start_date\":\"2026-10-08\",\"end_date\":\"2026-10-14\",\"content\":\"p-2\",\"views_total\":14,\"reach_total\":9}]", "mapping": { "business_account_key": "business", "platform": "channel", "period_start": "start_date", "period_end": "end_date", "post_key": "content", "impressions": "views_total", "reach": "reach_total" }, "metric_definition_ids": { "impressions": "post_impressions_v1", "reach": "account_reach_v1" } } ] } ``` # Actor output Schema ## `result` (type: `string`): Complete canonical records, account-period summaries, and comparable period deltas. ## `index` (type: `string`): Compact counts and a result key are stored in the default dataset. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "reports": [ { "format": "csv", "data": "acct,network,from,to,post,shown,unique_reach\nbrand-a,instagram,2026-10-01,2026-10-07,p-1,10,7", "mapping": { "business_account_key": "acct", "platform": "network", "period_start": "from", "period_end": "to", "post_key": "post", "impressions": "shown", "reach": "unique_reach" }, "metric_definition_ids": { "impressions": "post_impressions_v1", "reach": "account_reach_v1" } }, { "format": "json", "data": "[{\"business\":\"brand-a\",\"channel\":\"instagram\",\"start_date\":\"2026-10-08\",\"end_date\":\"2026-10-14\",\"content\":\"p-2\",\"views_total\":14,\"reach_total\":9}]", "mapping": { "business_account_key": "business", "platform": "channel", "period_start": "start_date", "period_end": "end_date", "post_key": "content", "impressions": "views_total", "reach": "reach_total" }, "metric_definition_ids": { "impressions": "post_impressions_v1", "reach": "account_reach_v1" } } ] }; // Run the Actor and wait for it to finish const run = await client.actor("althorlabs/social-metrics-reconciler").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "reports": [ { "format": "csv", "data": """acct,network,from,to,post,shown,unique_reach brand-a,instagram,2026-10-01,2026-10-07,p-1,10,7""", "mapping": { "business_account_key": "acct", "platform": "network", "period_start": "from", "period_end": "to", "post_key": "post", "impressions": "shown", "reach": "unique_reach", }, "metric_definition_ids": { "impressions": "post_impressions_v1", "reach": "account_reach_v1", }, }, { "format": "json", "data": "[{\"business\":\"brand-a\",\"channel\":\"instagram\",\"start_date\":\"2026-10-08\",\"end_date\":\"2026-10-14\",\"content\":\"p-2\",\"views_total\":14,\"reach_total\":9}]", "mapping": { "business_account_key": "business", "platform": "channel", "period_start": "start_date", "period_end": "end_date", "post_key": "content", "impressions": "views_total", "reach": "reach_total", }, "metric_definition_ids": { "impressions": "post_impressions_v1", "reach": "account_reach_v1", }, }, ] } # Run the Actor and wait for it to finish run = client.actor("althorlabs/social-metrics-reconciler").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "reports": [ { "format": "csv", "data": "acct,network,from,to,post,shown,unique_reach\\nbrand-a,instagram,2026-10-01,2026-10-07,p-1,10,7", "mapping": { "business_account_key": "acct", "platform": "network", "period_start": "from", "period_end": "to", "post_key": "post", "impressions": "shown", "reach": "unique_reach" }, "metric_definition_ids": { "impressions": "post_impressions_v1", "reach": "account_reach_v1" } }, { "format": "json", "data": "[{\\"business\\":\\"brand-a\\",\\"channel\\":\\"instagram\\",\\"start_date\\":\\"2026-10-08\\",\\"end_date\\":\\"2026-10-14\\",\\"content\\":\\"p-2\\",\\"views_total\\":14,\\"reach_total\\":9}]", "mapping": { "business_account_key": "business", "platform": "channel", "period_start": "start_date", "period_end": "end_date", "post_key": "content", "impressions": "views_total", "reach": "reach_total" }, "metric_definition_ids": { "impressions": "post_impressions_v1", "reach": "account_reach_v1" } } ] }' | apify call althorlabs/social-metrics-reconciler --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,althorlabs/social-metrics-reconciler" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/PvkHUiBpL2rT3zrvV/builds/GazH8wey2xxhlt3IJ/openapi.json