# US Brand Evidence Citation Table (`zinin/us-brand-evidence-citation-table`) Actor

Format buyer-supplied US-brand evidence into a deterministic citation table without fetching or verifying sources.

- **URL**: https://apify.com/zinin/us-brand-evidence-citation-table.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 Evidence Citation Table

Turn a small, buyer-owned evidence packet into a stable citation table for humans and machine-to-machine workflows. Submit normalized evidence rows and receive one deterministic JSON report, bounded Markdown citations, per-host and per-source counts, explicit limitations, and SHA-256 digests.

This Actor formats the evidence you provide. It does not browse, fetch, verify, rank, enrich, summarize, or infer facts. The facts, excerpts, and URLs are preserved in the JSON citation rows exactly after validation.

### What you submit and receive

You submit **1–100** rows. Every row has:

- a unique opaque ASCII `evidenceId`;
- `brandName`, `eventType`, `sourceName`, and a bounded factual `excerpt`;
- `observedAt` in strict UTC format `YYYY-MM-DDTHH:mm:ssZ`;
- an HTTPS `sourceUrl` without credentials, fragments, unsafe schemes, or a port other than 443.

You receive exactly one useful report row in the Dataset containing:

- `citations`, sorted by observed UTC, brand, event, source, URL, and evidence ID;
- the original facts and URLs, with no external lookup;
- `citationMarkdown`, a bounded Markdown table;
- `hostCounts` and `sourceCounts`;
- fixed warnings that sources were not fetched or verified and excerpts were not interpreted;
- input, citation, count, Markdown, and result SHA-256 digests.

The terminal `OUTPUT` receipt is written only after the named `result-found` Dataset push is confirmed. A delivery uncertainty is reported truthfully and the Actor never retries a possibly paid Dataset push.

### Input

```json
{
  "schemaVersion": "1.0",
  "rows": [
    {
      "evidenceId": "evidence-001",
      "brandName": "Northstar Coffee",
      "eventType": "price_change",
      "observedAt": "2026-07-31T09:30:00Z",
      "sourceName": "Buyer newsroom note",
      "sourceUrl": "https://example.com/northstar-price-note",
      "excerpt": "The buyer-supplied note says the seasonal blend price changed on July 31."
    }
  ]
}
```

#### Closed limits

The input is inline JSON only. The complete input is limited to **128 KiB UTF-8** and 100 rows. `evidenceId` is 1–64 ASCII characters. `brandName` and `sourceName` are 1–128 normalized characters. `eventType` is a 1–64 ASCII token. `sourceUrl` is 12–2,048 characters. `excerpt` is 1–2,000 normalized characters and at most 8 KiB UTF-8. Empty strings, leading/trailing whitespace, control characters, line breaks, duplicate IDs, invalid Gregorian dates, credentials, fragments, non-HTTPS schemes, and non-443 ports are rejected.

The report is limited to **64 KiB UTF-8** and its Markdown section to **48 KiB**. A valid packet that cannot fit these output limits fails closed instead of returning a partial citation table.

### Output and Dataset

The Dataset has one named result row. `citations` retains all seven input fields. `hostCounts` groups by the lower-case parsed URL hostname; `sourceCounts` groups by the exact source URL and includes that hostname. Counts are reconciled with `totalRows`, and all arrays are deterministically sorted.

No URL is opened. A valid URL means only that the submitted string passed the closed HTTPS syntax and safety rules; it is not evidence that the URL exists or supports the excerpt.

### Pricing

Pay per event: one start charge plus one `result-found` charge only after one confirmed report Dataset write. The default Dataset event is not charged by this Actor. The run preflight requires a budget for both events and rejects an already-used result counter.

| 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 |

### Machine-to-machine use

The Actor is stateless, keyless, and suitable for an agent calling the Apify API or an Apify MCP server. A machine can validate the closed input schema, send the same public-task-shaped JSON, read the single Dataset row, and verify `resultDigest` without a browser or a human login. The Actor never calls another Actor and never requires a proxy or BYOK key.

### Related public Actors

These public Actors can supply adjacent buyer-owned evidence workflows. Links are recommendations only; this Actor does not call them.

| Actor | Use it for |
| --- | --- |
| [US Brand Signal Metrics Aggregator](https://apify.com/zinin/us-brand-signal-metrics-aggregator) | Aggregate normalized signal rows before creating a citation packet. |
| [US Brand Signal Brief Composer](https://apify.com/zinin/us-brand-signal-brief-composer) | Compose a bounded brief after the citation table has been checked by the buyer. |
| [US Brand Action Queue](https://apify.com/zinin/us-brand-action-queue) | Turn selected, buyer-approved evidence into next-action rows. |
| [US Brand Evidence Snapshot Diff](https://apify.com/zinin/us-brand-evidence-snapshot-diff) | Compare two buyer-supplied evidence snapshots. |
| [US Brand Offer Evidence Normalizer](https://apify.com/zinin/us-brand-offer-evidence-normalizer) | Normalize offer evidence before citing it. |

### FAQ

**Does it verify the source?** No. It does not fetch URLs or make a claim that a source is real, current, or accurate.

**Does it infer a brand or event?** No. `brandName`, `eventType`, and the excerpt are buyer-provided and preserved.

**Why must timestamps be UTC?** A closed UTC form keeps sorting and digests reproducible across machines and time zones. Dates must also be valid in the Gregorian calendar, including leap years.

**Can I use it from an AI agent?** Yes. It is designed for schema-first API/MCP calls and returns a bounded single-row report with machine-verifiable digests.

**Why did a valid-looking packet fail?** It may exceed the input or output byte limits, contain a duplicate ID, an invalid date, unsafe URL syntax, or a field that is not normalized. The Actor does not truncate or return partial facts.

Built by Zinin for bounded, auditable evidence workflows.

# Actor input Schema

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

The only supported closed contract version.

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

One to 100 rows with unique opaque evidence IDs. All text is bounded; timestamps are strict UTC; source URLs must be HTTPS without credentials or fragments.

## Actor input object example

```json
{
  "schemaVersion": "1.0",
  "rows": [
    {
      "evidenceId": "evidence-001",
      "brandName": "Northstar Coffee",
      "eventType": "price_change",
      "observedAt": "2026-07-31T09:30:00Z",
      "sourceName": "Buyer newsroom note",
      "sourceUrl": "https://example.com/northstar-price-note",
      "excerpt": "The buyer-supplied note says the seasonal blend price changed on July 31."
    },
    {
      "evidenceId": "evidence-002",
      "brandName": "Northstar Coffee",
      "eventType": "product_launch",
      "observedAt": "2026-08-01T12:00:00Z",
      "sourceName": "Buyer product page",
      "sourceUrl": "https://example.com/northstar-seasonal",
      "excerpt": "The buyer-supplied excerpt describes a seasonal blend launch for August."
    },
    {
      "evidenceId": "evidence-003",
      "brandName": "Harbor Supply",
      "eventType": "campaign",
      "observedAt": "2026-08-02T15:45:00Z",
      "sourceName": "Buyer campaign brief",
      "sourceUrl": "https://example.com/harbor-campaign",
      "excerpt": "The buyer-supplied brief names a back-to-school campaign and its stated launch date."
    }
  ]
}
```

# 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 citation table 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": [
        {
            "evidenceId": "evidence-001",
            "brandName": "Northstar Coffee",
            "eventType": "price_change",
            "observedAt": "2026-07-31T09:30:00Z",
            "sourceName": "Buyer newsroom note",
            "sourceUrl": "https://example.com/northstar-price-note",
            "excerpt": "The buyer-supplied note says the seasonal blend price changed on July 31."
        },
        {
            "evidenceId": "evidence-002",
            "brandName": "Northstar Coffee",
            "eventType": "product_launch",
            "observedAt": "2026-08-01T12:00:00Z",
            "sourceName": "Buyer product page",
            "sourceUrl": "https://example.com/northstar-seasonal",
            "excerpt": "The buyer-supplied excerpt describes a seasonal blend launch for August."
        },
        {
            "evidenceId": "evidence-003",
            "brandName": "Harbor Supply",
            "eventType": "campaign",
            "observedAt": "2026-08-02T15:45:00Z",
            "sourceName": "Buyer campaign brief",
            "sourceUrl": "https://example.com/harbor-campaign",
            "excerpt": "The buyer-supplied brief names a back-to-school campaign and its stated launch date."
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("zinin/us-brand-evidence-citation-table").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": [
        {
            "evidenceId": "evidence-001",
            "brandName": "Northstar Coffee",
            "eventType": "price_change",
            "observedAt": "2026-07-31T09:30:00Z",
            "sourceName": "Buyer newsroom note",
            "sourceUrl": "https://example.com/northstar-price-note",
            "excerpt": "The buyer-supplied note says the seasonal blend price changed on July 31.",
        },
        {
            "evidenceId": "evidence-002",
            "brandName": "Northstar Coffee",
            "eventType": "product_launch",
            "observedAt": "2026-08-01T12:00:00Z",
            "sourceName": "Buyer product page",
            "sourceUrl": "https://example.com/northstar-seasonal",
            "excerpt": "The buyer-supplied excerpt describes a seasonal blend launch for August.",
        },
        {
            "evidenceId": "evidence-003",
            "brandName": "Harbor Supply",
            "eventType": "campaign",
            "observedAt": "2026-08-02T15:45:00Z",
            "sourceName": "Buyer campaign brief",
            "sourceUrl": "https://example.com/harbor-campaign",
            "excerpt": "The buyer-supplied brief names a back-to-school campaign and its stated launch date.",
        },
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("zinin/us-brand-evidence-citation-table").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": [
    {
      "evidenceId": "evidence-001",
      "brandName": "Northstar Coffee",
      "eventType": "price_change",
      "observedAt": "2026-07-31T09:30:00Z",
      "sourceName": "Buyer newsroom note",
      "sourceUrl": "https://example.com/northstar-price-note",
      "excerpt": "The buyer-supplied note says the seasonal blend price changed on July 31."
    },
    {
      "evidenceId": "evidence-002",
      "brandName": "Northstar Coffee",
      "eventType": "product_launch",
      "observedAt": "2026-08-01T12:00:00Z",
      "sourceName": "Buyer product page",
      "sourceUrl": "https://example.com/northstar-seasonal",
      "excerpt": "The buyer-supplied excerpt describes a seasonal blend launch for August."
    },
    {
      "evidenceId": "evidence-003",
      "brandName": "Harbor Supply",
      "eventType": "campaign",
      "observedAt": "2026-08-02T15:45:00Z",
      "sourceName": "Buyer campaign brief",
      "sourceUrl": "https://example.com/harbor-campaign",
      "excerpt": "The buyer-supplied brief names a back-to-school campaign and its stated launch date."
    }
  ]
}' |
apify call zinin/us-brand-evidence-citation-table --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

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