# US Brand Signal Cross-Tabulator (`zinin/us-brand-signal-cross-tabulator`) Actor

Build a deterministic complete two-dimensional count matrix from buyer-supplied opaque rows, including zero cells, totals, basis points, and stable digests.

- **URL**: https://apify.com/zinin/us-brand-signal-cross-tabulator.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 Cross-Tabulator

US Brand Signal Cross-Tabulator builds a deterministic two-dimensional count table from buyer-supplied opaque rows. It is useful for compact segmentation such as `eventType x status`, `brand x reviewState`, or `sourceClass x outcome` when an agent already owns the observations.

The Actor does not fetch a website, resolve an ID, identify a person or company, verify a source, or infer causality. It only counts the rows in the request.

### What you submit and receive

You submit 1 to 100 unique rows. Each row has:

- `rowId`: a unique printable ASCII identifier;
- `rowDimension`: one of at most 15 printable ASCII row categories;
- `columnDimension`: one of at most 15 printable ASCII column categories.

You receive one Dataset report with:

- every row/column combination, including cells with count `0`;
- `rowTotals` and `columnTotals`;
- `rowPercentBasisPoints`, `columnPercentBasisPoints`, and `overallPercentBasisPoints` for every cell;
- explicit denominator definitions, sorted values, and SHA-256 digests;
- a truthful `OUTPUT` receipt after one confirmed Dataset write.

Basis points are integers from 0 to 10000. For example, `5000` means 50%. Each percentage is rounded independently to the nearest basis point. The report states the denominator for each field: the row total, the column total, or all input rows.

### Run it

1. Open **Try for free** in the Actor Console.
2. Paste the exact JSON shape shown in the Input section.
3. Start the run and read the one report row from the Dataset.
4. Read the terminal delivery receipt from `OUTPUT`.

The runnable prefill is also available in `examples/input.json` and `public-task.json`.

### Pricing

Pay per event: **$0.005 per run start plus $0.010 per delivered result** on the FREE tier. The result event is emitted only after one confirmed Dataset write. The Actor checks that the buyer cap covers both charges before processing.

| Tier | Discount | Start | Delivered result |
| --- | ---: | ---: | ---: |
| FREE | 0% | $0.00500 | $0.01000 |
| BRONZE | 5% | $0.00475 | $0.00950 |
| SILVER | 10% | $0.00450 | $0.00900 |
| GOLD | 15% | $0.00425 | $0.00850 |
| PLATINUM | 18% | $0.00410 | $0.00820 |
| DIAMOND | 20% | $0.00400 | $0.00800 |

Invalid input, insufficient cap, uncertain delivery, and an uncharged or multiply charged result are not reported as successful results. The Actor never retries a paid Dataset push.

### Freshness and determinism

There is no external freshness because this Actor does not fetch data and does not read the clock. Refresh the rows in your upstream system and rerun when observations change. The same rows always produce the same matrix and digests regardless of input order.

### Input

```json
{
  "schemaVersion": "1.0",
  "rows": [
    {"rowId": "observation-001", "rowDimension": "enterprise", "columnDimension": "accepted"},
    {"rowId": "observation-002", "rowDimension": "enterprise", "columnDimension": "review"},
    {"rowId": "observation-003", "rowDimension": "startup", "columnDimension": "accepted"},
    {"rowId": "observation-004", "rowDimension": "startup", "columnDimension": "rejected"},
    {"rowId": "observation-005", "rowDimension": "enterprise", "columnDimension": "accepted"}
  ]
}
```

### Output

The Dataset has one deterministic report item. `matrix` is sorted by `rowDimension`, then `columnDimension`, and contains the full Cartesian product of observed dimensions. `OUTPUT` contains the terminal delivery receipt and links represented by the Store output schema.

### Related public Actors

These Actors can feed or use the same buyer-owned analytics workflow. This Actor does not call them.

| Actor | Use it for |
| --- | --- |
| [US Brand Signal Metrics Aggregator](https://apify.com/zinin/us-brand-signal-metrics-aggregator) | Summarize numeric signal rows before building a cross-tabulation. |
| [US Brand Signal Brief Composer](https://apify.com/zinin/us-brand-signal-brief-composer) | Turn a submitted matrix and totals into a bounded brief. |
| [US Brand Action Queue](https://apify.com/zinin/us-brand-action-queue) | Convert selected matrix segments into next-action rows. |
| [US Brand Evidence Snapshot Diff](https://apify.com/zinin/us-brand-evidence-snapshot-diff) | Compare two buyer-supplied matrix or evidence snapshots. |
| [US Brand Offer Evidence Normalizer](https://apify.com/zinin/us-brand-offer-evidence-normalizer) | Normalize offer evidence before tabulating dimensions. |

### Limitations

- Dimension values are opaque ASCII IDs and are not treated as names, people, companies, or verified entities.
- The maximum input is 100 rows, 15 unique row dimensions, and 15 unique column dimensions.
- Duplicate row IDs and extra fields fail closed.
- The report is bounded below 64 KiB. A mathematically valid input that would exceed the bound returns `output_too_large` rather than a partial result.
- There is no network, proxy, BYOK key, LLM, clock, state, child Actor, or Dataset input.
- JSON Schema validates shape; runtime validators additionally enforce sorting, complete zero cells, basis-point reconciliation, and digest integrity.

### FAQ

**Why are zero cells included?** A complete matrix makes absence explicit and lets downstream machines compare shapes without guessing whether a cell was omitted.

**What does a basis-point denominator mean?** Row basis points use that cell's row total; column basis points use its column total; overall basis points use all submitted rows. The `denominators` object repeats these definitions in the report.

**Does the matrix prove a relationship?** No. It is only a count of buyer-supplied rows.

**Can I submit URLs or names?** The contract accepts opaque ASCII IDs only. The Actor does not resolve URLs or identity.

**What happens after uncertain delivery?** The Actor records a non-success terminal receipt and does not issue a second Dataset write.

Built by [zinin](https://apify.com/zinin).

# Actor input Schema

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

The only supported closed contract version.

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

One to 100 unique opaque rows. There can be at most 15 unique rowDimension values and 15 unique columnDimension values.

## Actor input object example

```json
{
  "schemaVersion": "1.0",
  "rows": [
    {
      "rowId": "observation-001",
      "rowDimension": "enterprise",
      "columnDimension": "accepted"
    },
    {
      "rowId": "observation-002",
      "rowDimension": "enterprise",
      "columnDimension": "review"
    },
    {
      "rowId": "observation-003",
      "rowDimension": "startup",
      "columnDimension": "accepted"
    },
    {
      "rowId": "observation-004",
      "rowDimension": "startup",
      "columnDimension": "rejected"
    },
    {
      "rowId": "observation-005",
      "rowDimension": "enterprise",
      "columnDimension": "accepted"
    }
  ]
}
```

# Actor output Schema

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

API link to the terminal receipt when OUTPUT was stored.

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

API link to the one deterministic report row after confirmed result delivery.

# 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": [
        {
            "rowId": "observation-001",
            "rowDimension": "enterprise",
            "columnDimension": "accepted"
        },
        {
            "rowId": "observation-002",
            "rowDimension": "enterprise",
            "columnDimension": "review"
        },
        {
            "rowId": "observation-003",
            "rowDimension": "startup",
            "columnDimension": "accepted"
        },
        {
            "rowId": "observation-004",
            "rowDimension": "startup",
            "columnDimension": "rejected"
        },
        {
            "rowId": "observation-005",
            "rowDimension": "enterprise",
            "columnDimension": "accepted"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("zinin/us-brand-signal-cross-tabulator").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": [
        {
            "rowId": "observation-001",
            "rowDimension": "enterprise",
            "columnDimension": "accepted",
        },
        {
            "rowId": "observation-002",
            "rowDimension": "enterprise",
            "columnDimension": "review",
        },
        {
            "rowId": "observation-003",
            "rowDimension": "startup",
            "columnDimension": "accepted",
        },
        {
            "rowId": "observation-004",
            "rowDimension": "startup",
            "columnDimension": "rejected",
        },
        {
            "rowId": "observation-005",
            "rowDimension": "enterprise",
            "columnDimension": "accepted",
        },
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("zinin/us-brand-signal-cross-tabulator").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": [
    {
      "rowId": "observation-001",
      "rowDimension": "enterprise",
      "columnDimension": "accepted"
    },
    {
      "rowId": "observation-002",
      "rowDimension": "enterprise",
      "columnDimension": "review"
    },
    {
      "rowId": "observation-003",
      "rowDimension": "startup",
      "columnDimension": "accepted"
    },
    {
      "rowId": "observation-004",
      "rowDimension": "startup",
      "columnDimension": "rejected"
    },
    {
      "rowId": "observation-005",
      "rowDimension": "enterprise",
      "columnDimension": "accepted"
    }
  ]
}' |
apify call zinin/us-brand-signal-cross-tabulator --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

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