# Powder Evidence response fields: coverage, GAP and Evidence Score

This reference lists every part of a Powder Evidence response: coverage, the evidence records, the Evidence Score, the interpretation, and the request fields the API accepts or rejects. Each call to `POST https://agents.dubbleblack.com/zcj/dqgz0d7tl8ox/api/agent/evidence` costs $0.10 per request, and every successful answer is a paid answer, including a GAP. Read coverage first, then the records and their limitations, then the score: the response reports what was observed, at what grain and from where, and the calling agent decides what it supports.

## At a glance

- **Endpoint:** `POST https://agents.dubbleblack.com/zcj/dqgz0d7tl8ox/api/agent/evidence` with a JSON body holding at least one selector, usually `query`
- **Price:** $0.10 per request, the same on Pay as you go and on Credits
- **Payment:** a 402 is the price quote. You pay it over x402 (Base USDC) or MPP (Tempo USDC) and retry the same request. A per-call payment needs no account or bearer credential.
- **Card:** card pays a pay-as-you-go call only at $0.50 or more. To fund calls by card, buy Credits from $0.50 with a buyer identity.
- **Response:** JSON with `evidence_available`, `evidence`, `coverage`, `evidence_score`, `interpretation` and `errors`
- **GAP:** a successful, paid answer meaning Powder holds no relevant evidence. It is not negative evidence about a product.
- **Evidence Score:** bounded 0 to 100. It measures evidence strength and depth only.
- **Full purchase flow:** [buyer skill](https://agents.dubbleblack.com/zcj/dqgz0d7tl8ox/SKILL.md)

## Top-level fields

The schema requires `schema_version`, `generated_at`, `evidence_available`, `evidence` and `errors`, and allows additional properties.

| Field | Type | Meaning |
| --- | --- | --- |
| `schema_version` | string | Response schema version |
| `generated_at` | date-time string | When the answer was generated |
| `request` | object | The request fields as Powder read them, with defaults filled in |
| `evidence_available` | boolean | `true` when at least one relevant, legitimate observable signal exists |
| `evidence` | array | The evidence records |
| `results_returned` | number | How many records were returned |
| `errors` | array of strings | Errors for this answer |
| `coverage` | object | What Powder holds for the question |
| `coverage_state` | string | The coverage state, repeated at the top level |
| `evidence_score` | object or null | The Evidence Score |
| `interpretation` | object | How the question was read and routed |
| `provenance` | array | The provenance object of each record |
| `limitations` | array of strings | Limits that apply to the whole answer |
| `owned_evidence`, `external_evidence`, `brand_provided_evidence` | arrays | Records grouped by origin |
| `evidence_types`, `evidence_depth`, `evidence_granularity` | array, number, array | Types, depth and granularity across the records |
| `stage_timings_ms`, `plan`, `acquisition` | objects | Processing time per stage, the provider plan and the external acquisition record |
| `legacy_outcome_depth` | array | Carried over from the earlier version: per subject, `subject_id`, `observed_count` and `status` |
| `comparison_subjects` | array | Present only for an explicit two-subject comparison |

An example answer to a request with `limit` 5 held four evidence records and four provenance objects, and paid $0.10.

## Coverage states

`coverage.state` reports one of four states. The documentation names them in capitals, but the recorded GAP answer below sends `"gap"` in lower case, so compare the value without regard to case.

| State | Meaning | What to do |
| --- | --- | --- |
| `OWNED` | Relevant evidence is held and returned by Powder | Read the records and their limitations |
| `SUPPLEMENTED` | Powder returns relevant evidence at a wider grain, or at an extra grain beside the one asked for | Check each record's `identity_granularity` before applying it to one product |
| `EXTERNAL` | Reserved for explicitly enabled external evidence | - |
| `GAP` | No relevant owned evidence was found. The answer is successful and paid. | Report that Powder holds no evidence. Do not count it against the product. |

The `coverage` object also carries `owned_evidence_available`, `external_evidence_attempted` and `external_evidence_used` (booleans); `providers_considered`, `providers_attempted` and `providers_used` (lists); `gap_reason` (null unless there is a gap); `requested_identity_levels`, `available_identity_levels` and `missing_identity_levels`; `gap_dimensions`; and `external_acquisition_status` with `external_acquisition_reason`. In the example evidence answer, five providers were considered, none attempted and one used, with one identity level available and none missing.

## Evidence records

Each entry in `evidence` is one observation with its limits.

| Field | Meaning |
| --- | --- |
| `evidence_type`, `signal_type` | The kind of evidence and the signal observed. Powder's evidence types are catalog, behavioral click and observed conversion. |
| `observed_count` | Number of observations. `provenance.counting_unit` names what was counted. |
| `status` | Observation status, kept for compatibility. Aggregate observations use `observed`. |
| `identity_granularity`, `identity_basis` | The grain the evidence identifies, such as product or brand, and how it was matched. Broader brand or offer evidence is never promoted to product identity. |
| `subject_id`, `product_name`, `brand` | The evidence subject. A returned subject is not a recommendation. |
| `source`, `source_authority` | Where the record comes from and that source's authority |
| `provenance` | `source_type`, `evidence_grain`, `counting_unit`, `transaction_level`, `reporting_period_start`, `reporting_period_end`, `retrieved_at`, `raw_source_digest`, `canonical_resolution_status`, counts of product outcomes by status (confirmed, declined, pending), and source identifiers |
| `limitations` | What this record cannot show. Read it before using the record. |
| `origin` | The origin of the record |
| `commerce_status`, `source_status`, `status_history` | Observed conversions stay observed conversions, with commerce status unknown. Source dispositions are kept apart from observation status. |
| `time_window`, `observed_at`, `freshness` | Timing fields, null when not set |

Each record in the example evidence answer carried one limitation.

## Evidence Score

`evidence_score` is a calibrated, bounded score from 0 to 100. It measures the strength and depth of the evidence. It does not rate the product, the confidence of a recommendation or the chance of a purchase.

| Field | Meaning |
| --- | --- |
| `score` | The sum of bounded components |
| `band` | The label for the score |
| `version`, `calibration_status` | Score version and calibration state |
| `summary` | A plain-language reading of the score |
| `components` | `evidence_diversity`, `evidence_depth`, `evidence_granularity`, `outcome_evidence`, `behavioral_evidence`, `catalog_identity`, `provenance_quality`, `freshness`, `behavioral_depth`, `outcome_depth`, `identity_strength`, `source_diversity`, `context_relevance`. Each is a number or null. |
| `formula` | How the components combine |
| `component_notes` | Notes on individual components |
| `limitations` | Limits on what the score shows |

## Interpretation and comparisons

`interpretation` shows how the question was read: `original_query`, `normalized_query`, `entity_text`, `requested_vertical`, `resolved_vertical`, `routing_reason`, `category`, `brand`, the requested `product_ids`, `gtins`, `skus` and identity levels, the `evidence_types` searched, and `relevance`.

`comparison_subjects` appears only for an explicit two-subject question in `query`. Every entry holds one subject with its own evidence, coverage, provenance, limitations and score. Powder calculates no winner and no combined score.

## A GAP answer

This request asks about a product outside Powder's evidence:

```bash
curl -i -X POST https://agents.dubbleblack.com/zcj/dqgz0d7tl8ox/api/agent/evidence \
  -H 'Content-Type: application/json' \
  -d '{"query": "Which cordless drill should I buy for home projects?", "limit": 3, "max_external_sources": 0}'
```

After the 402 is paid, the answer is a successful response. The example below paid $0.10. An excerpt, with other fields omitted:

```json
{
  "schema_version": "2.0",
  "evidence_available": false,
  "evidence": [],
  "results_returned": 0,
  "errors": [],
  "coverage": {
    "state": "gap",
    "owned_evidence_available": false,
    "providers_attempted": [],
    "providers_used": [],
    "gap_reason": "external_acquisition_disabled",
    "available_identity_levels": [],
    "missing_identity_levels": []
  },
  "evidence_score": {
    "score": 0,
    "band": "limited",
    "version": "v1",
    "calibration_status": "calibrated",
    "limitations": ["no relevant owned evidence"],
    "formula": "score=sum(bounded components); depth uses 20+20*log10(count), capped",
    "component_notes": {"score_meaning": "evidence strength only; not product quality or purchase likelihood"}
  },
  "coverage_state": "gap"
}
```

In this answer `interpretation.resolved_vertical` is null, eight score components are 0 and five are null.

## Request fields

At least one selector is required: `query`, `intent`, `vertical`, `category`, `brand`, `brands`, `product_ids`, `gtins` or `skus`. Fields outside this list are not accepted.

| Field | Accepted values |
| --- | --- |
| `query` | String, up to 2000 characters. One subject or an explicit comparison of two. |
| `intent` | String, up to 512 characters |
| `vertical`, `category` | Strings, up to 128 characters. Optional routing hints; unknown values are accepted. |
| `brand` | String, up to 128 characters. `brands` takes exactly one item as an alias. |
| `product_ids`, `gtins`, `skus` | Arrays of exactly one string, up to 128 characters |
| `evidence_types` | Up to 10 of `behavioral`, `outcome`, `product`, `catalog`, `price`, `promotion`, `availability`, `intent_context`, `external` |
| `requested_identity_levels` | Up to 9 of `product`, `sku`, `gtin`, `variant`, `offer`, `brand`, `category`, `merchant`, `unknown` |
| `limit` | Integer 1 to 10, default 5. The most records returned. |
| `max_external_sources` | Integer 0 to 10, default 2. Both examples on this page send `0`. |
| `context` | Object |

## Rejected requests and errors

| Status | Meaning | Action |
| --- | --- | --- |
| 400 | Invalid body, `budget_min`, `budget_max` or `include_insufficient_evidence` sent, an ambiguous multi-selector request, or more than two subjects | Fix the body: one selector, or one two-subject `query` |
| 401 | Authentication failure. A pay-as-you-go call needs no bearer credential. | Check the payment proof and headers |
| 402 | The price quote | Pay it and retry the same request |
| 429 | Rate limit exceeded | Wait for `Retry-After`, then retry |
| 500 | The evidence service failed closed | Check whether the call was charged before you retry |

Payment errors are listed in the [error reference](https://agents.dubbleblack.com/zcj/dqgz0d7tl8ox/errors.md).

## Frequently asked questions

### What does a GAP mean in a Powder response?

A GAP means Powder found no relevant owned evidence for the question. It is a successful response, not an API failure, and it says nothing against the product. `evidence_available` is `false`, `evidence` is empty and `coverage.gap_reason` gives the reason.

### Is a GAP answer charged?

Yes. Every call costs $0.10 per request whatever it finds, and the example GAP answer above paid $0.10.

### Does the Evidence Score rate the product?

No. The score measures how strong and deep the evidence is, from 0 to 100. It does not rate the product, the confidence of a recommendation or the chance of a purchase, and Powder makes no recommendation. Read it with coverage and each record's limitations.

### Can Powder compare two products?

Yes, when `query` names exactly two subjects. The answer lists each in `comparison_subjects` with its own evidence, coverage, limitations and score. No winner or combined score is calculated, and three or more subjects return a 400.

### Can I pay for one request by card?

Not on its own: card pays a pay-as-you-go call only at $0.50 or more. Pay single requests over x402 or MPP, or buy Credits from $0.50 by card with a buyer identity at `POST https://agents.dubbleblack.com/zcj/dqgz0d7tl8ox/plans/{planId}/purchase`, with the plan listed in the catalog.

## Keep reading

- [Buyer skill](https://agents.dubbleblack.com/zcj/dqgz0d7tl8ox/SKILL.md): the full purchase flow
- [Powder Evidence API reference](https://agents.dubbleblack.com/zcj/dqgz0d7tl8ox/services/powder-evidence/openapi.json): request and response schema
- [How to pay](https://agents.dubbleblack.com/zcj/dqgz0d7tl8ox/payment.md): rails, Credits and top-ups
- [Error reference](https://agents.dubbleblack.com/zcj/dqgz0d7tl8ox/errors.md): every error code and its recovery
- [Catalog](https://agents.dubbleblack.com/zcj/dqgz0d7tl8ox/manifest.json): live prices and plans

---

Updated 2026-10-16. All DubbleBlack guides: https://agents.dubbleblack.com/guides.md. Storefront: https://agents.dubbleblack.com/zcj/dqgz0d7tl8ox/llms.txt.