---
title: "HitKeep Analytics Opportunity Recommendations Guide | HitKeep"
description: "Generate saved HitKeep Opportunities from deterministic analytics detectors, optional AI enrichment, and a localization-safe recommendations API."
canonical: "https://hitkeep.com/guides/analytics/opportunities/"
---

# HitKeep Analytics Opportunity Recommendations Guide

Opportunities answer the operator question: **Know what to review next.** They turn existing HitKeep analytics into saved, evidence-backed recommendation records for conversion signals, traffic sources, Web Vitals performance issues, AI visibility gaps, search visibility, and setup gaps worth reviewing.

The important boundary is simple: detectors decide what exists. AI is optional and may only help choose approved localized copy from cited evidence.

Route production AI through a gateway

HitKeep has a rudimentary global AI request and token limiter. It is a coarse process-level safeguard, not per-user, per-site, per-provider-key, or a security policy engine. For production use, route model traffic through an AI gateway or provider policy layer that can enforce detailed quotas, model allowlists, key isolation, audit logging, redaction, and network controls. See GoAI’s [supported provider options](https://goai.sh/providers/) and [generic OpenAI-compatible provider](https://goai.sh/providers/compat.html) docs for the underlying base URL, token, header, and custom endpoint patterns.

## What the page shows

The **Opportunities** page ranks saved recommendations for the active site.

Each item includes:

- type, score, confidence, and workflow status
- impact label and value based on the detector evidence
- the dashboard route or source the recommendation points to
- cited evidence such as checkout starts, orders, AI crawler requests, pageviews, sessions, tracked events, overall top city, overall top provider, or overall top ASN
- the next action text rendered from localization keys and interpolation params

The workflow statuses are:

| Status | Meaning |
| --- | --- |
| new | Generated and not yet triaged. |
| saved | Kept for follow-up. |
| done | Marked complete by a permitted user. |
| dismissed | Hidden from the normal active list. |

## Generation model

Generation runs in two phases.

1. HitKeep loads analytics for the selected site and date range.
2. Deterministic detectors create candidate Opportunities.
3. If AI is enabled, configured, and inside the local budget, HitKeep asks the provider to select approved copy keys and cite evidence for each candidate.
4. HitKeep validates the output and saves only the final structured recommendation.

If AI is disabled or not configured, detector output is still saved. The dashboard can still show localized recommendations because the detector output already uses translation keys and params.

## Current detector families

The first detector set reads data HitKeep already stores:

| Detector type | Input data | When it appears |
| --- | --- | --- |
| checkout_conversion | Ecommerce summary plus aggregate city, provider, and ASN context | Checkout starts exist and checkout conversion is below the detector threshold. |
| ai_visibility | AI fetch overview plus optional site traffic support and aggregate city, provider, and ASN context | AI crawler requests exist for the site. |
| traffic_quality | Site overview stats, top sources, and aggregate city, provider, and ASN context | The site has actionable source traffic with source-specific counts, enough sample size, and meaningful share in the selected range. |
| performance | Web Vitals p75 summary plus page, city, provider, and ASN breakdowns | Web Vitals samples show a poor or needs-improvement metric with enough aggregate evidence. |
| search_visibility | Imported Search Console aggregates | Impressions exist with room to improve clicks or position. |
| conversion_signal | Site traffic, events, ecommerce, and existing setup | Tracked events exist but the site still lacks a clear conversion signal. |
| setup_goal_suggestion | Setup evidence from events and goals | A conversion-like event repeats enough times and no matching goal exists. |
| setup_funnel_suggestion | Setup evidence from paths, events, and funnels | A likely path-to-event conversion flow appears and no matching funnel exists. |

The detectors assign opportunity type, impact, confidence, score, status, evidence, and cited evidence IDs. AI stays inside the allowlisted detector contract and cannot publish an unsupported opportunity type.

HitKeep does not create a placeholder Opportunity for a site with no usable signal. Setup suggestions require direct aggregate evidence, such as repeated conversion-like events or a repeated path-to-event flow. Performance recommendations require Web Vitals samples and cite aggregate metrics, not raw browser debug fields. When city, provider, or ASN context is available, detectors may cite only aggregate labels such as overall top city, overall top provider, and overall top ASN. They do not persist raw IP addresses, user agents, or visitor rows as Opportunity evidence. If a new site has no pageviews, events, ecommerce activity, Web Vitals samples, AI fetches, Search Console rows, or setup evidence yet, generation returns `no_opportunities`.

## Localization-safe API contract

Opportunity API responses do not return full translated prose as the contract. They return keys and params that the dashboard translates.

Important fields include:

| Field | Purpose |
| --- | --- |
| title_key, summary_key, action_key, digest_key | Translation keys for customer-visible copy. |
| copy_params | Interpolation values for those keys, for example conversion rate, source, source-specific visits, total pageviews, path, or estimated search clicks. |
| impact_label_key and impact_value | Localized impact label plus detector value. |
| route_label_key, route_params, and route_icon | Where the UI points the user next. |
| evidence[].label_key, evidence[].value, and cited_evidence_ids | The evidence shown to the user and the evidence IDs the copy is allowed to reference. |
| detector_version | The detector contract that produced the record. |
| ai_run_id | Present on authenticated site responses when AI enrichment succeeded. Omitted from shared dashboard responses. |

This keeps the API useful for any supported dashboard language and avoids storing customer-facing English as the durable product contract. Opportunity recommendations do not expose `monthly_upside` or financial promise fields; ecommerce analytics pages can still report factual revenue metrics.

Saved Opportunities can be included in the regular daily or weekly email digest. There is no separate “Opportunities email” to configure. `GET /api/sites/{id}/opportunities/digest-preview?frequency=weekly` previews the safe digest payload for a site, using the same key-and-placeholder contract without persisting a new run.

## Permissions

| Action | Required permission |
| --- | --- |
| List saved Opportunities | site.view |
| Generate or regenerate Opportunities | site.manage_data |
| Save, dismiss, or mark done | site.manage_data |
| View through a share link | Valid share token for that site. The response omits internal AI run and team fields. |
| Configure AI provider settings | Instance owner or admin operating the runtime configuration. |

API clients and MCP clients can read saved Opportunities only when their token can view the site.

## Enable AI enrichment

AI enrichment is disabled by default. Configure the HitKeep route and local budgets on the HitKeep process. Configure provider credentials with the selected goAI provider’s own environment variables. Use the [goAI supported providers documentation](https://goai.sh/providers/) for provider-specific auth and endpoint variables.

For AWS-billed self-hosted installs, the recommended default is GPT OSS 120b through Amazon Bedrock Mantle’s OpenAI-compatible endpoint:

```
HITKEEP_AI_ENABLED=true
HITKEEP_AI_PROVIDER=openai-compatible
HITKEEP_AI_MODEL=openai.gpt-oss-120b
HITKEEP_AI_BASE_URL=https://bedrock-mantle.eu-central-1.api.aws/v1
HITKEEP_AI_REGION=eu-central-1
HITKEEP_AI_REQUEST_LIMIT=100
HITKEEP_AI_TOKEN_LIMIT=100000
HITKEEP_AI_BUDGET_WINDOW=1440
```

On EC2, ECS, or another AWS runtime, prefer an instance or task role that can call Bedrock. For local smoke tests, you can pass a temporary Bedrock bearer token through `HITKEEP_AI_API_KEY`.

The full setup guide is [AI Model Configuration](https://hitkeep.com/guides/admin/ai-model-configuration/). It covers model choice, Bedrock Mantle, direct Bedrock, HitKeep route fields, goAI provider credential variables, token budgets, and System Status behavior.

Use a direct OpenAI route when you want the provider to handle auth and billing:

```
HITKEEP_AI_ENABLED=true
HITKEEP_AI_PROVIDER=openai
HITKEEP_AI_MODEL=your-json-capable-model
OPENAI_API_KEY=your-provider-key
```

Use an OpenAI-compatible gateway such as LiteLLM or Bifrost when an internal gateway owns routing. Set `HITKEEP_AI_PROVIDER=openai-compatible`, use the gateway route as `HITKEEP_AI_MODEL`, and set `HITKEEP_AI_BASE_URL`. Authentication is optional for the generic compatible provider. Set `HITKEEP_AI_API_KEY` only when your gateway requires a bearer token.

For direct region-scoped Bedrock, use AWS credentials and region variables:

```
HITKEEP_AI_ENABLED=true
HITKEEP_AI_PROVIDER=bedrock
HITKEEP_AI_MODEL=amazon.nova-lite-v1:0
AWS_REGION=eu-central-1
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
```

See the [AI Model Configuration](https://hitkeep.com/guides/admin/ai-model-configuration/) guide for setup examples and the [Configuration Reference](https://hitkeep.com/reference/configuration/#optional-ai-model-configuration) for the full provider list, defaults, timeout, and budget fields.

## Budget and status

HitKeep enforces local request and token budgets before provider calls. This is separate from provider or gateway limits.

`HITKEEP_AI_TOKEN_LIMIT` is the local budget for counted provider tokens in the configured window. It is not the model context window. The Opportunities enrichment call expects a compact JSON object and caps provider output at 900 tokens before validation.

The admin AI status endpoint and System Status page can show:

- `disabled`
- `not_configured`
- `configured`
- `budget_exhausted`
- `needs_attention`

Safe error categories include `auth_failed`, `rate_limited`, `timeout`, `budget_exhausted`, `invalid_output`, `canceled`, and `provider_error`.

Raw prompts, raw provider responses, raw external error bodies, and provider secrets are not returned by status endpoints.

## Privacy and audit boundary

AI run records keep operational metadata:

- team, site, actor, and feature
- provider and model label
- prompt template version
- cited evidence IDs
- input and output hashes
- final validated structured output
- token and request usage when available
- lifecycle events such as request start, request finish, tool call start, tool call finish, latency, status, and safe error category

HitKeep does not persist raw prompts or raw provider payloads for Opportunities. Provider secrets are redacted from logs and status responses.

## Email digests

Opportunities are part of the regular report system. When saved recommendations are ready for a site, the digest renderer can include the same localized title/action keys, params, score, confidence, route hints, and cited aggregate evidence that the dashboard shows.

The email path does not trigger a new AI run and does not include raw prompts, raw provider output, or unrestricted tool data. It reads saved records and renders the same safe customer-visible fields.

## MCP, share links, and takeout

Saved Opportunities can appear outside the dashboard through controlled surfaces:

- [MCP](https://hitkeep.com/guides/integrations/mcp/) exposes saved Opportunities as final safe records for visible sites.
- [Share links](https://hitkeep.com/guides/sharing/dashboard-links/) can read saved Opportunities for the shared site, without internal team or AI run fields.
- [Site takeout](https://hitkeep.com/guides/data/takeout/) includes saved Opportunities and safe AI run metadata, but excludes provider secrets and raw AI payloads.

These surfaces do not expose unrestricted AI tools, raw hit/session rows, IP addresses, user agents, raw prompts, or raw provider responses.

## Related

- [AI Model Configuration](https://hitkeep.com/guides/admin/ai-model-configuration/)
- [Configuration Reference](https://hitkeep.com/reference/configuration/#optional-ai-model-configuration)
- [System Status and Settings](https://hitkeep.com/guides/admin/system-administration/#ai-status)
- [Roles and Permissions](https://hitkeep.com/guides/admin/permissions/)
- [Official MCP Server](https://hitkeep.com/guides/integrations/mcp/#opportunities-arguments)
- [Analytics with Open Exports](https://hitkeep.com/guides/data/takeout/#export-opportunities)
- [Web Vitals Analytics](https://hitkeep.com/guides/analytics/web-vitals/)
- [AI Visibility Analytics](https://hitkeep.com/guides/analytics/ai-visibility/)
- [Ecommerce Analytics](https://hitkeep.com/guides/analytics/ecommerce/)

[Previous Web Vitals analytics](https://hitkeep.com/guides/analytics/web-vitals/)[Next Ask AI](https://hitkeep.com/guides/analytics/ask-ai/)