# Explore a catalog

Use `catalog_local_v1` to request selected outputs across a catalog. Start in
[Catalogs](/catalogs/new), or call the API from your server. For work combining
title, research and content requests, review the steps in [Recipes](/recipes).

## Access, limits and cost

Catalog actions require a bound shared wallet and a key with `match` or `batch`;
status/results require `read`. The console also checks session eligibility and
workflow capabilities. [Key scopes](/docs/key-scopes) do not override account access.

The API accepts 1-500 submitted titles per catalog call. The console demo allows
100 records and a 160,000-byte request body. Splitting a catalog into separate
calls creates separately priced work and independently computed groups.
The default active-job limit is two per tenant; unaccepted quotes do not take
an execution slot. Current quote creation still counts toward daily title quota.

Each selected output costs one configured parameter unit per catalog call,
regardless of title count. Individual title requests instead price each selected
parameter for each title. Read the exact catalog quote before accepting; do not
estimate a catalog charge by multiplying the number of titles. Wallet credits
are Reach Dog billing units, not provider model tokens.

Successful empty results are charged. Required-stage failure does not deliver
a paid partial result. Saved result reads and completed same-key replay do not
generate another answer or debit. A new request key can create separately charged work.

## Choose outputs

| Name | Register ID | Purpose |
| --- | --- | --- |
| catalog_summary | 52 | Catalog profile and seasonal summary |
| catalog_groups | 54 | Grouping lenses across the catalog |
| group_members | 55 | Products belonging to each group |
| ungrouped_items | 56 | Products not assigned to a group |
| catalog_products | None | Prepared product records and catalog health details |
| catalog_briefing | None | Catalog briefing with keyword and content context |
| catalog_questions | None | Questions about the catalog profile |
| catalog_ghost_opportunities | None | Products with missed search opportunities and SEO suggestions |
| catalog_keyword_opportunities | None | Keyword opportunities |
| catalog_content_ideas | None | Content ideas |

Use output names for the six unnumbered outputs. Registered parameters 53, 57,
58 and 59 are not selectable in this workflow. Catalog product records do not
provide all fields from individual title enrichment. Suggested opportunities
are candidates for review, not independently verified facts.
New product records expose the submitted `brand` explicitly. Use
`matched_cluster_id` for the taxonomy match ID. The deprecated `cluster` field
retains its old brand value for compatibility; it is not a grouping lens or
taxonomy label. Older saved results may omit `brand` and are not rewritten.

## Quote, accept, wait and read

1. Save a stable request key and submit `POST /v1/batches` with an
   `Idempotency-Key` header and this request shape:

```json
{
  "workflow": "catalog_local_v1",
  "records": [{"client_product_id": "product-1", "title": "Waterproof camping tent"}],
  "parameters": ["catalog_groups", "group_members"]
}
```

2. Save the returned batch ID. Inspect `billing.quote` and `billing.acceptance`.
   No generation starts until explicit acceptance. If submission times out,
   recover using the same request key and unchanged body.
3. Submit `POST /v1/batches/{id}/accept` with
   `{"acceptance":"the exact billing.acceptance value from the quote"}`.
   Do not replace or recalculate the binding. Acceptance can fail for an active-job
   limit; keep the same job and retry acceptance after capacity is available.
4. Poll `GET /v1/batches/{id}`, honoring `Retry-After`. Keep the batch ID when
   you stop waiting. Stopping local polling does not cancel server work.
5. On completion, read `GET /v1/batches/{id}/results?page_size=100` and send the
   returned `next_cursor` as `cursor` while `has_more` is true. Top-level list
   outputs page; scalar objects repeat and should be retained once. Arrays
   nested in a scalar object do not become independent result pages.

The console displays all returned outputs, including generic views for outputs
without a specialized renderer. Selecting an output does not certify its quality
for your catalog; inspect results before using them downstream.

## Cancellation and payment recovery

`POST /v1/batches/{id}/cancel` asks the server to cancel. Payment protections can
refuse cancellation while settlement is uncertain. Keep polling the existing job
so the worker can reconcile its existing payment; do not create a new job or key.

`POST /v1/batches/{id}/retry-payment` is for a definitive, retryable refusal
(`insufficient_credits` or `wallet_frozen`) after its cause is resolved. Send the
original accepted binding. It reuses the staged result; it is not a general
retry instruction for an uncertain settlement or a generation failure.

## Retention and local drafts

The default catalog job retention is seven days; inspect the returned expiry.
Single title, research and content results default to 24 hours. These lifetimes
are not promises about when an idempotency key can be reused. Cleanup is
asynchronous, and regenerating expired work can charge again.

Catalog drafts are stored only in this browser for this account. Clearing site
data or switching devices loses the draft, but retained submitted catalog runs
can be found in [History](/history) for the same API account. Open a catalog to
read its saved status and results without starting work or making a payment.
Load further result pages when offered; downloads include only loaded pages.
Expired or deleted catalogs are not recoverable there. Save the batch ID and
request plan for API recovery before expiry. Downloading or viewing a plan does not send it.
