# US Brand Signal Metrics Aggregator (`zinin/us-brand-signal-metrics-aggregator`) Actor

Aggregate deterministic metrics from already collected US brand signal rows without network access.

- **URL**: https://apify.com/zinin/us-brand-signal-metrics-aggregator.md
- **Developed by:** [Tim Zinin](https://apify.com/zinin) (community)
- **Categories:** MCP servers, Automation, Marketing
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## US Brand Signal Metrics Aggregator

Deterministic, machine-friendly metrics for US brand signal rows you already collected.

Paste 1-100 rows and receive one report with event-type, severity, status, source, confidence, warning, and digest metrics. The Actor is intentionally stateless and does not browse, use proxies, call an LLM, read a Dataset, store replay state, or accept URLs.

### What you provide

Each closed row contains `signalId`, `eventType`, `severity`, `sourceName`, `confidenceBps`, and `status`. Text is printable ASCII only. IDs must be unique. The complete serialized request is at most 128 KiB.

### What you receive

The result includes zero-inclusive enum counts, source counts sorted by ASCII key, confidence sum, half-up integer average, active/resolved totals, high-or-critical count, deterministic warnings, and SHA-256 input/result digests. The successful run writes exactly one report row and attempts one terminal `OUTPUT` receipt. Persistent KVS failure means no stored `OUTPUT` is promised; the run fails with a fixed redacted reason after a bounded recovery attempt.

### Example task

Use the public task to run three sample signals from a brand newsroom and retail monitor. It produces an average confidence of 7200 bps and exposes warnings for high-or-critical, low-confidence, and resolved signals.

### Pricing

This is pay-per-event pricing with one `apify-actor-start` event and one `result-found` event for a successful report. The six tiers are:

| Tier | Actor start | One result |
| --- | ---: | ---: |
| FREE | $0.005000 | $0.010000 |
| BRONZE | $0.004750 | $0.009500 |
| SILVER | $0.004500 | $0.009000 |
| GOLD | $0.004250 | $0.008500 |
| PLATINUM | $0.004100 | $0.008200 |
| DIAMOND | $0.004000 | $0.008000 |

No default Dataset event is configured. Invalid inputs and unsafe pricing are rejected before any result event or Dataset row.

### Limits and privacy

The Actor is limited to 512 MB and 90 seconds. It performs no network access, accepts no BYOK key, uses no proxy, and keeps no state between runs. It processes only the rows submitted in the current request.

### FAQ

#### Can I send URLs or timestamps?

No. This Actor summarizes normalized signals. Use an upstream collector to obtain source data, then pass the six-field rows here.

#### Does input order matter?

No. Unique signal IDs are sorted before processing and digesting.

#### Can an AI agent call it?

Yes. The closed schema, deterministic output, public task, and MCP category are designed for machine-to-machine use.

### Related public Actors

| Actor | Use it for |
| --- | --- |
| [US Brand Action Queue](https://apify.com/zinin/us-brand-action-queue) | Turn verified signal rows into a deterministic priority queue before aggregating portfolio metrics. |
| [US Brand Offer Evidence Normalizer](https://apify.com/zinin/us-brand-offer-evidence-normalizer) | Normalize observed US brand offers into stable evidence rows for downstream measurement. |
| [US Brand Federal Award Snapshot](https://apify.com/zinin/us-brand-federal-award-snapshot) | Collect official federal-award evidence that can feed a broader brand-signal workflow. |
| [Competitor Change Rollup](https://apify.com/zinin/competitor-change-rollup) | Consolidate competitor changes before computing counts, confidence, and status metrics. |
| [Trademark Multiregistry](https://apify.com/zinin/trademark-multiregistry) | Add trademark evidence to a launch or brand-risk signal set. |

The buyer-facing contract is fully described above. The Store image is a square 512x512 PNG using opaque red `#E10A17` and white only, with white signal bars and a small checkmark on the red field; it has no text, gradients, shadows, transparency, or third-party marks.

# Actor input Schema

## `schemaVersion` (type: `string`):

Required closed V1 contract.

## `rows` (type: `array`):

One to 100 closed rows. signalId is unique and all text is printable ASCII only.

## Actor input object example

```json
{
  "schemaVersion": "1.0",
  "rows": [
    {
      "signalId": "nike-launch-001",
      "eventType": "product_launch",
      "severity": "high",
      "sourceName": "Brand newsroom",
      "confidenceBps": 9200,
      "status": "active"
    },
    {
      "signalId": "nike-price-001",
      "eventType": "price_change",
      "severity": "medium",
      "sourceName": "Retail monitor",
      "confidenceBps": 7600,
      "status": "resolved"
    },
    {
      "signalId": "nike-review-001",
      "eventType": "review",
      "severity": "low",
      "sourceName": "Retail monitor",
      "confidenceBps": 4800,
      "status": "active"
    }
  ]
}
```

# Actor output Schema

## `OUTPUT` (type: `string`):

API link to the terminal receipt when the bounded OUTPUT write succeeds; unavailable when persistent KVS failure prevents storage.

## `report` (type: `string`):

API link to the deterministic report row after confirmed delivery; pre-delivery failures, including unsafe pricing, create no explanatory row.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "schemaVersion": "1.0",
    "rows": [
        {
            "signalId": "nike-launch-001",
            "eventType": "product_launch",
            "severity": "high",
            "sourceName": "Brand newsroom",
            "confidenceBps": 9200,
            "status": "active"
        },
        {
            "signalId": "nike-price-001",
            "eventType": "price_change",
            "severity": "medium",
            "sourceName": "Retail monitor",
            "confidenceBps": 7600,
            "status": "resolved"
        },
        {
            "signalId": "nike-review-001",
            "eventType": "review",
            "severity": "low",
            "sourceName": "Retail monitor",
            "confidenceBps": 4800,
            "status": "active"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("zinin/us-brand-signal-metrics-aggregator").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "schemaVersion": "1.0",
    "rows": [
        {
            "signalId": "nike-launch-001",
            "eventType": "product_launch",
            "severity": "high",
            "sourceName": "Brand newsroom",
            "confidenceBps": 9200,
            "status": "active",
        },
        {
            "signalId": "nike-price-001",
            "eventType": "price_change",
            "severity": "medium",
            "sourceName": "Retail monitor",
            "confidenceBps": 7600,
            "status": "resolved",
        },
        {
            "signalId": "nike-review-001",
            "eventType": "review",
            "severity": "low",
            "sourceName": "Retail monitor",
            "confidenceBps": 4800,
            "status": "active",
        },
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("zinin/us-brand-signal-metrics-aggregator").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "schemaVersion": "1.0",
  "rows": [
    {
      "signalId": "nike-launch-001",
      "eventType": "product_launch",
      "severity": "high",
      "sourceName": "Brand newsroom",
      "confidenceBps": 9200,
      "status": "active"
    },
    {
      "signalId": "nike-price-001",
      "eventType": "price_change",
      "severity": "medium",
      "sourceName": "Retail monitor",
      "confidenceBps": 7600,
      "status": "resolved"
    },
    {
      "signalId": "nike-review-001",
      "eventType": "review",
      "severity": "low",
      "sourceName": "Retail monitor",
      "confidenceBps": 4800,
      "status": "active"
    }
  ]
}' |
apify call zinin/us-brand-signal-metrics-aggregator --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=zinin/us-brand-signal-metrics-aggregator",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/eFmrSomnb3hmucEDy/builds/JIie6r6geLxFWMN2p/openapi.json