# Personal Settings & Notifications
Source: https://docs.devtune.ai/account-billing/account-settings
Configure your personal DevTune profile, notification preferences, appearance, password, MFA, and project-specific notification overrides.
This page covers the **personal settings** surface inside a team workspace. It is separate from team-level management, billing, API keys, and webhooks.
Use it when you want to manage:
* Your own profile
* Notification delivery and project-specific overrides
* Appearance preferences
* Password, MFA, and account deletion
## Accessing Personal Settings
From inside a team workspace:
1. Open the user menu
2. Go to **User**
3. Use the **Profile** and **Notifications** tabs
## Profile Tab
The **Profile** tab is where you manage your personal identity and login settings.
### Profile details
Use this tab to update:
* Display name
* Email address
* Profile picture
These values appear across shared team surfaces such as activity, comments, and invitations.
### Security and authentication
Depending on your auth setup, this page can also include:
* Password changes
* Linked authentication providers
* Multi-factor authentication
* Account deletion
## Notifications Tab
The **Notifications** tab controls what interrupts you immediately and what stays in scheduled digests.
### Notification presets
Start with a preset that matches how you work:
* **Docs** - Bias toward docs/source regressions and keep digests lightweight
* **Growth / DevRel** - Track coverage regressions, competitor threats, and weekly actions digests
* **Founder** - Keep interruptions low-noise and favor summary emails for material issues
### Notification scope
You can apply settings:
* Across **all projects** as your default
* Or as a **project-specific override** for one project
This is useful when one project needs tighter monitoring than the rest of the workspace.
### Immediate alerts
These are the alert families worth interrupting you for:
* **Coverage regression**
* **Docs / source regression**
* **Competitor threat**
Coverage and docs/source alerts use a **Sensitivity** setting. Competitor threat uses a **Minimum threat** threshold.
### Reports and digests
These are useful to review, but not worth an interruption:
* **Weekly summary report**
* **Actions digest**
The actions digest supports a **daily** or **weekly** cadence.
### Collaboration
* **@mentions** - Notify you when someone mentions you in an action comment
## Appearance
Use your theme preference to switch between:
* **Light**
* **Dark**
* **System**
## Security Notes
Personal settings are also where you handle account-level security actions such as:
* Password updates
* MFA enrollment
* Reviewing linked auth methods
* Personal account deletion
If you are the primary owner of a team, transfer ownership before deleting your personal account.
## What This Page Does Not Manage
This page is only for your personal settings inside the team workspace.
Use other account-level pages for:
* **Team** - Team name, slug, members, invites, auto-join, and ownership
* **Billing** - Plans, usage, invoices, and content credits
* **API Keys** - Project-scoped keys for API and MCP access
* **Webhooks** - Event subscriptions and signing secrets
* **Agent Activity** - Audit log of recent API requests
## Next Steps
* **[Account & Billing Overview](/account-billing/overview)** - See the full account-level layout
* **[Team Management](/account-billing/team-management)** - Manage the shared team workspace
* **[Alerts & Notifications](/insights-actions/alerts)** - See how notification types map to product events
# Agent Activity
Source: https://docs.devtune.ai/account-billing/agent-activity
Audit recent DevTune API and AI agent traffic across your account by API key, project, endpoint, scope, status code, and request latency.
The **Agent Activity** page is the account-level audit view for recent DevTune API usage.
It is designed for teams that want visibility into how internal tools, automations, and AI agents are using the DevTune API.
## What the Page Shows
Agent Activity displays a recent request log across the account, including:
* **When** the request happened
* **Project**
* **API key**
* **Method**
* **Endpoint**
* **Status**
* **Scope**
* **Latency**
* **Error / rate limit state**
The page shows a recent request window rather than long-term historical analytics. Use it as an operational audit surface.
## What It Is Useful For
Agent Activity helps answer questions like:
* Which integrations are actively using the API?
* Which projects are receiving the most programmatic traffic?
* Are requests failing because of scope or authorization issues?
* Are certain endpoints slower or more error-prone than expected?
* Is a key still being used after it should have been retired?
## Common Workflows
### Debugging an integration
1. Open **Agent Activity**
2. Find the affected endpoint or project
3. Check status codes, scopes, and error fields
4. Confirm the expected key is being used
### Auditing key usage
1. Review recent activity by key
2. Identify keys with no recent usage
3. Revoke unused keys from **API Keys**
### Reviewing agent behavior
1. Confirm agents or automations are only hitting the expected endpoints
2. Check response status and latency
3. Validate that assigned scopes match the intended access surface
## Permissions
Agent Activity is available on plans that include API access.
## Best Practices
* Use distinct API keys for distinct integrations so the log stays attributable
* Check Agent Activity after changing scopes or rotating secrets
* Review rate-limited or error-heavy endpoints before widening access
## Next Steps
* **[API Keys](/account-billing/api-keys)** - Create, scope, or revoke keys
* **[Authentication](/api-reference/authentication)** - Review how keys and scopes work
* **[Webhooks](/api-reference/webhooks)** - Pair outbound event delivery with inbound API usage
# API Keys
Source: https://docs.devtune.ai/account-billing/api-keys
Create, scope, expire, and revoke project-scoped DevTune API keys for the public REST API and MCP server, all managed from the team-account sidebar.
The **API Keys** page is the account-level UI for managing project-scoped keys used by the DevTune API and MCP server.
Each key belongs to exactly one project, but key management happens from the team-account sidebar so your team can see all keys in one place.
## What the API Keys Page Shows
The page shows a table of existing keys across the account, including:
* **Name**
* **Key prefix**
* **Project**
* **Status**
* **Scopes**
* **Expiration**
* **Last used**
* **Created date**
If you have revoked keys, you can use the **Hide revoked** toggle to keep the table focused on active credentials.
## Creating a Key
Click **Create API Key** to open the creation dialog.
When creating a key, you choose:
* A friendly **name**
* The **project** the key should access
* An optional **expiration**
* The allowed **API scopes**
After creation, DevTune shows the raw key **once**. Copy it immediately and store it securely.
## Scopes
API keys can be left broad or narrowed to specific endpoint groups.
Use scopes when you want to:
* Limit a BI dashboard to read-only visibility data
* Restrict automation to actions or webhook management
* Give an agent the smallest access surface it needs
If a key has all scopes selected, it behaves like a full-access key for that project.
New scope families are never added to an existing key automatically. To use
page metrics, Audit, Outcomes, AI referrals, or managed agents, open the
key's **Scopes** dialog and explicitly grant the corresponding scope.
## Updating and Revoking Keys
From the table you can:
* Open the **Scopes** dialog to narrow or expand endpoint access
* **Revoke** a key you no longer trust or need
Revocation is immediate. Revoked keys stop working and can remain visible in the table when you disable **Hide revoked**.
## Expiration
Keys support optional expiration windows such as:
* No expiration
* 30 days
* 60 days
* 90 days
* 180 days
* 1 year
Use short-lived keys for temporary automations or contractor access.
## Permissions
Only team members with the `settings.manage` permission can manage API keys.
## Best Practices
* Create separate keys for separate systems
* Name keys after the integration that owns them
* Prefer scoped keys over full-access keys
* Use expiration for temporary access
* Revoke keys immediately when an integration is retired
## Next Steps
* **[Authentication](/api-reference/authentication)** - Learn how to use keys in requests
* **[MCP Server](/api-reference/mcp-server)** - Connect agent tooling with scoped keys
* **[Agent Activity](/account-billing/agent-activity)** - Audit how keys are being used
# Credit transactions
Source: https://docs.devtune.ai/account-billing/credit-transactions
Read the account Transactions ledger for allowances, purchases, content generation, and agent-run costs.
The **Transactions** ledger on the Billing page explains every addition to or use of the account's shared credit balance.
## Open Transactions
1. Open the account workspace
2. Select **Billing** in the account sidebar
3. Find **Transactions** beside the plan and credit controls
The ledger is visible to account members who can open Billing. Billing-management permission is still required to change plans or buy credit packs.
## Read a transaction
Each row shows:
* **Date** in UTC
* **Activity** that added or used credits
* **Details**, including the project when available
* A signed **Amount**
A positive amount adds credits. A negative amount spends or expires credits. Agent and other usage can include fractional credits, so the ledger can show more precision than the rounded balance elsewhere in the product.
## Activity types
The ledger can include:
* **Monthly allowance** and **Monthly allowance expired**
* **Credit pack**
* **Credit adjustment**
* **Content generation** and **Content generation refund**
* **Agent run pending**, **Agent run estimate**, and **Agent run completed**
The ledger keeps plan allowance and purchased credits in one account balance. Monthly allowance credits expire on the next billing anniversary. Purchased credit packs do not expire, and DevTune spends the expiring allowance before purchased credits.
## Agent run transactions
An agent run uses a reserve-then-settle flow:
1. **Agent run pending** reserves the estimated credits before the run starts.
2. When the run finishes, **Agent run completed** shows the final measured cost.
3. The pending estimate is marked **Replaced by final amount** and displayed with a line through it so it is not mistaken for an additional charge.
Select **View run** to open the corresponding agent run when its project is still available.
If a run is still active, the pending reservation remains labeled **Pending**. A final agent transaction is labeled **Settled**.
## Browse older transactions
Transactions display 20 rows per page. Use **Previous** and **Next** to move through older activity. The page indicator shows your position in the available history.
## Next steps
* [Understand agent models and credits](/agents/models-and-credits)
* [Manage Account & Billing](/account-billing/overview)
# Account & Billing
Source: https://docs.devtune.ai/account-billing/overview
Manage your DevTune team workspace including team membership, billing plans, shared credits, API keys, webhooks, and API activity logs.
The account-level area is where you manage the shared workspace around your projects: team membership, billing, usage, credits, API keys, webhooks, and API activity.
## What Lives at the Account Level
Use the account-level sidebar for:
* **Account Home** - View and launch projects
* **Team** - Manage team settings, members, invites, and auto-join
* **Billing** - Manage plans, usage, credits, and transaction history
* **API Keys** - Create and manage keys for programmatic access
* **Webhooks** - Subscribe to project events
* **Agent Activity** - Audit recent API traffic across the account
Some of these routes depend on your plan.
## Billing
The **Billing** page combines plan management with operational usage context.
### Plan management
From the billing page you can:
* Review your current subscription
* Upgrade or change plans
* Open the billing portal for invoices and subscription management
* Purchase add-on credit packs
* Review every allowance, purchase, content workflow, and agent-run transaction
### Usage
The billing page also summarizes plan usage for:
* **Projects**
* **AI Search prompts**
* **Credits**
## Credits
Credits power agent runs, brief generation, and related content workflows.
Your account holds a single credit balance. Two things fund it, and
everything that consumes credits spends from the same pool.
### The monthly plan allowance
Every paid plan adds its monthly allowance to the balance on your billing
anniversary, whether you pay monthly or annually.
* **Starter** — 10 credits per month
* **Plus** — 20 credits per month
* **Pro** — 50 credits per month
* **Agency / Enterprise** — 100 credits per month for each project
* The allowance expires on your next billing anniversary, not at the end of the calendar month
* Usage is still recorded against the project that consumed the credits, so you can see where they were spent
* Automatic brief prewarming can use only a capped portion of the monthly allowance, so it should not consume the whole allowance by itself
### Purchased add-on credits
You can buy one-time credit packs from the billing page:
* `25` credits
* `50` credits
* `100` credits
Purchased credits **never expire** and are shared across the account.
### How credits are spent
Spending always takes the expiring part of the balance first, so a month's
allowance is used before the credits you bought. Purchased credits are what
remain once the allowance runs out, which means you never lose bought credits
to an expiry you could have avoided.
Everywhere except the **Transactions** ledger, DevTune shows one number: the credits
remaining. There is nothing to choose between and no confirmation step before
a brief spends a credit.
### Transactions
The **Transactions** ledger shows credits added to or used from the shared balance. Agent runs first appear as a pending reservation and then as one settled final amount based on measured model usage.
## API Keys
On plans that include API access, the account sidebar includes **API Keys**.
Use API keys when you need to:
* Call the DevTune API from your own systems
* Pull project data into internal tooling
* Connect MCP-compatible agents
* Automate reporting or downstream workflows
## Webhooks
On plans that include API access, the account sidebar also includes **Webhooks**.
Use webhooks to receive real-time notifications when important project events happen, such as tracking runs completing or visibility changes landing in the system.
## Agent Activity
On plans that include API access, the account sidebar also includes **Agent Activity**.
Use it to audit:
* Which projects are receiving API traffic
* Which API keys are being used
* Which endpoints are being called
* Response status, scope, and latency for recent requests
## Team Management
The **Team** page controls who can access the workspace and what they can manage.
In practice:
* **Owners** manage billing, roles, and critical account settings
* **Members** collaborate on projects, actions, and analysis without owning billing operations
## Plan Notes
* **Starter / Plus** include Community Discourse thread coverage, AI Search, and monthly content credits
* **Pro** adds AI Demand and broader AI Search / Community Discourse coverage
* **Plus and above** unlock API keys, webhooks, agent activity, and the MCP server
## Next Steps
* **[API Keys](/account-billing/api-keys)** - Create and manage project-scoped API keys
* **[Credit Transactions](/account-billing/credit-transactions)** - Review allowances, purchases, content usage, and agent-run costs
* **[Agent Models and Credits](/agents/models-and-credits)** - Understand model bands, estimates, and settlement
* **[Agent Activity](/account-billing/agent-activity)** - Audit recent API usage
* **[Personal Settings & Notifications](/account-billing/account-settings)** - Configure your own profile and notification preferences
* **[Team Management](/account-billing/team-management)** - Invite members and manage roles
* **[Webhooks](/api-reference/webhooks)** - Review the event payloads and delivery model
# Team Management
Source: https://docs.devtune.ai/account-billing/team-management
Manage your DevTune team workspace settings, members, invitations, roles, domain auto-join, and ownership transfer from the Team page.
The **Team** page is the shared workspace-management surface for a team account. It is where you manage the team record itself and control who can access the workspace.
## Team Page Structure
The Team page has two tabs:
* **Settings** - Team name, slug, and team-account configuration
* **Members** - Current members, invitations, and auto-join settings
## Roles and Permissions
DevTune uses two workspace roles:
* **Owner**
* **Member**
### Owner
Owners can:
* Manage billing and subscriptions
* Change member roles
* Remove members
* Manage critical team settings
* Transfer ownership when they are the primary owner
* Delete the team account when they are the primary owner
Each team has one primary owner and may also have additional owners when needed.
### Member
Members can:
* View projects and shared data
* Work with project settings and recommendations
* Invite new members where the relevant permission is available
Members cannot manage billing, ownership, or destructive team operations.
## Members Tab
The **Members** tab is where you manage the people and invitations attached to the team.
### Current members
From the members table you can:
* Review the current roster
* See each member's role
* Update roles when you have permission
* Remove members when appropriate
### Invitations
The pending invitations area lets you:
* Invite a new member
* Review outstanding invites
* Cancel stale invitations
### Auto-join
If the primary owner has a supported work-email domain, the Members tab can also show **Team Auto-Join**.
Use it to allow new users with the same work-email domain to discover and join the team automatically.
## Settings Tab
The **Settings** tab is for the team account itself.
Use it to manage:
* Team name
* Team slug
* Team deletion
Deletion is permanent and should be treated as a destructive operation.
## Common Workflows
### Invite a teammate
1. Open **Team**
2. Go to **Members**
3. Click **Invite Member**
4. Enter their email
5. Choose the role
6. Send the invitation
### Change a role
1. Open **Team > Members**
2. Find the member
3. Update their role if you have `roles.manage`
### Enable auto-join
1. Open **Team > Members**
2. Find **Team Auto-Join**
3. Enable it for the detected work-email domain
### Remove a member
1. Open **Team > Members**
2. Find the member
3. Remove them if you have `members.manage`
## Best Practices
* Keep the number of additional owners as low as practical
* Remove departed teammates promptly
* Use auto-join only for domains you control
* Review invitations and role assignments regularly
## Next Steps
* **[Personal Settings & Notifications](/account-billing/account-settings)** - Configure your own profile and alerts
* **[Account & Billing Overview](/account-billing/overview)** - See the rest of the account-level surfaces
# Adoption Dashboard
Source: https://docs.devtune.ai/adoption-tracking/dashboard
Navigate the DevTune Adoption Metrics dashboard to interpret npm and PyPI download trends, GitHub stars, market share, and competitive positioning.
The Adoption Metrics dashboard provides a comprehensive view of your package or library's adoption metrics. This page walks through each section of the dashboard and explains how to interpret the data.
> **DevTune 2.0:** This dashboard is available only in the legacy project experience. Accounts using the 2.0 project experience return to Project Home when opening its former route. Existing adoption data collection remains in place during the UI deprecation period.
## Accessing the Dashboard (legacy experience)
These steps apply to the legacy project experience only; 2.0 projects no longer show this dashboard.
1. Select your project from the account home page
2. In the sidebar, open **Adoption Metrics**
3. Review the dashboard
## Time Range Selection
A dropdown in the top-right corner lets you select the time range for all dashboard data:
* **7 days** - Recent activity
* **30 days** (default) - Monthly view
* **90 days** - Quarterly trends
* **6 months** - Half-year view
* **1 year** - Annual trends
* **All** - Full history
The selected range persists as a URL parameter, so you can bookmark or share specific views.
> **Note:** The Competitor Movement section always compares against 30 days ago, regardless of the selected time range. This provides a consistent reference point for competitive changes.
## Adoption Health Score
The Health Score is a 0-100 gauge displayed prominently in the top-left of the dashboard. It provides an at-a-glance assessment of your adoption health.
### Score Ranges
| Range | Label | Meaning |
| -------- | --------------- | ------------------------------------------- |
| 70-100 | Excellent | Strong and growing adoption |
| 55-69 | Good | Healthy adoption with room for improvement |
| 40-54 | Needs Attention | Adoption is flat or declining in some areas |
| Below 40 | Critical | Significant adoption challenges |
### Score Breakdown
Hover over the Health Score to see a tooltip showing how each component contributes to the total:
* **Download Growth** (up to 35 points) - How your recent downloads compare to the prior period. Strong growth earns more points.
* **Market Share Trend** (up to 25 points) - Whether your share of total tracked downloads is growing, stable, or declining.
* **Star Growth** (up to 20 points) - GitHub star growth over the selected time range.
* **Competitive Position** (up to 20 points) - Your ranking among tracked competitors by download count. First place earns the most points.
Each component is color-coded green (above 50% of max) or red (below 50%) so you can quickly see what is helping or hurting your score.
## Summary Stats
Four cards to the right of the Health Score show key metrics:
### Your Downloads
The 4-week average of weekly downloads for your primary package. This smooths out day-to-day fluctuations and gives a stable measure of your current download volume.
### Your Market Share
Your percentage of total downloads across all tracked packages. If you track your package plus three competitors, and you account for 40% of total downloads, your market share is 40%.
### Your Rank
Your position among all tracked packages, ranked by download count. A rank of 1 means you have the most downloads among the packages you track.
### Growth Rate
The 3-month download growth percentage for your primary package. A positive value means downloads are increasing; negative means they are declining.
## Competitor Movement
The Competitor Movement section ("What's Changed") shows four cards highlighting competitive shifts over the last 30 days:
* **Your Market Share** - Current market share percentage with the change from 30 days ago
* **Your Rank** - Current rank with change direction
* **Fastest Growing Competitor** - Which competitor is growing fastest and their growth rate
* **Closest Competitor** - Which competitor is nearest to you by download count, and the gap
This section requires at least 30 days of data to display. Until then, it shows an "Insufficient history" message.
## AI Visibility vs Adoption Correlation
This chart overlays your AI search visibility metrics (Presence Rate, Share of Voice, Sentiment) with your adoption data (downloads) over time. It also displays Pearson correlation coefficients for each visibility metric.
This helps answer questions like:
* Does improved AI visibility lead to more downloads?
* Is there a lag between visibility changes and adoption changes?
* Which visibility metric correlates most strongly with adoption?
> **Note:** This section only appears if you have both AI Search data and adoption data for the same time period.
## Code Repositories
If you have GitHub repositories configured as tracked URLs, this section displays:
### GitHub Stars Trend
A multi-line area chart showing GitHub stars over time for your repositories and competitors. Your primary repository is highlighted in green; competitors appear in contrasting colors.
### Leaderboard
A sortable table comparing all tracked repositories:
| Column | Description |
| ------------ | ----------------------------------- |
| Name | Repository name |
| Growth (3m) | Star growth over the last 3 months |
| Growth (6m) | Star growth over the last 6 months |
| Growth (12m) | Star growth over the last 12 months |
| GitHub Stars | Current total star count |
Click any column header to sort. Your primary repository is marked with a star icon.
## Package Registries
If you have package registry URLs configured as tracked URLs, this section displays:
### Weekly Downloads Trend
A multi-line area chart showing weekly download counts over time. Data is smoothed with a 28-day rolling average to reduce noise. Your primary package is highlighted; competitors appear in different colors.
### Market Share Trend
A multi-line chart showing each package's percentage of total tracked downloads over time. This reveals whether you are gaining or losing ground relative to competitors.
### Leaderboard
A sortable table comparing all tracked packages:
| Column | Description |
| ---------------- | ---------------------------------------------- |
| Name | Package name |
| 4w Avg Downloads | Average weekly downloads over the last 4 weeks |
| Growth (3m) | Download growth over the last 3 months |
| Growth (6m) | Download growth over the last 6 months |
| Growth (12m) | Download growth over the last 12 months |
Click any column header to sort. Your primary package is marked with a star icon.
## Setting Up Tracked URLs
The **Configure Tracked URLs** button at the bottom of the dashboard links to your project's tracked-URL setup. To add or modify tracked packages and repositories:
1. Go to your project's **Project Settings > Brands**
2. Select the relevant brand in the left-hand list
3. Add tracked URLs with the appropriate type:
* **GitHub repository** (e.g., `github.com/your-org/your-repo`) for star tracking
* **Package registry** (e.g., `npmjs.com/package/your-package`, `pypi.org/project/your-package`) for download tracking
4. Assign each tracked URL to a brand (your primary brand or a competitor brand)
Data collection begins automatically after tracked URLs are added. Historical data (up to one year for npm) is backfilled when a new package is first configured.
## Best Practices
### Choose Meaningful Competitors
Track competitors that your users actually consider as alternatives. Tracking too many or irrelevant competitors dilutes the usefulness of market share and ranking metrics.
### Review Regularly
* **Weekly** - Check summary stats and competitor movement for short-term shifts
* **Monthly** - Review health score trends and download growth rates
* **Quarterly** - Analyze longer-term market share trends and correlation data
### Combine with AI Visibility Data
Use the AI Visibility vs Adoption Correlation chart to validate whether your content strategy improvements are translating into adoption. Strong positive correlation between presence rate and downloads suggests your AI Search efforts are working.
## Next Steps
* **[Adoption Metrics Overview](/adoption-tracking/overview)** - Understand the feature and key concepts
* **[Tracked URLs](/search-tracking/domains)** - Configure the tracked URLs that feed adoption data
* **[Search Analytics](/analytics/search-analytics)** - Explore your AI visibility data alongside adoption
# Adoption Metrics Overview
Source: https://docs.devtune.ai/adoption-tracking/overview
Monitor your SDK or library adoption across package registries and GitHub with download trends, market share, and competitive positioning.
Adoption Metrics gives you a clear picture of how your SDK, library, or open-source project is being adopted. It pulls data from package registries (npm, PyPI, crates.io, NuGet, RubyGems) and GitHub to show download trends, market share, and competitive positioning in a single dashboard.
> **DevTune 2.0:** The standalone Adoption dashboard is retired for accounts using the 2.0 project experience. Those accounts return to Project Home when opening the legacy dashboard route. Accounts on the legacy experience retain the dashboard, and adoption data continues to be collected while backend cleanup is deferred.
## What Adoption Metrics Covers
Adoption Metrics answers the question: **How is my package or library performing relative to competitors, and is adoption growing?**
DevTune automatically collects:
* **Weekly download counts** from package registries (npm, PyPI, crates.io, NuGet, RubyGems)
* **GitHub star counts** from code repositories
* **Market share** across all tracked packages in your category
* **Growth rates** at 3-month, 6-month, and 12-month intervals
* **Competitive rankings** against the competitors you track
## Why Adoption Metrics Matters
### Developer Advocates Need Data
If you are a developer advocate, developer relations lead, or product manager for a developer tool, you need to answer stakeholder questions like:
* Is our SDK growing?
* How do we compare to competitors?
* Are our content and community efforts driving real adoption?
Adoption Metrics provides the data to answer these questions with confidence.
### Connect AI Visibility to Adoption
DevTune uniquely connects your AI search visibility data with adoption metrics. The dashboard includes a correlation chart that shows how changes in your AI presence rate, share of voice, and sentiment relate to download trends. This helps you understand whether improved AI visibility translates into real adoption.
## Plan Requirements
Adoption Metrics is available on paid plans that include the adoption entitlement.
## Supported Registries and Platforms
DevTune collects adoption data from the following sources:
### Package Registries
| Registry | Data Collected |
| --------- | ---------------------- |
| npm | Weekly download counts |
| PyPI | Weekly download counts |
| crates.io | Weekly download counts |
| NuGet | Download counts |
| RubyGems | Download counts |
### Code Platforms
| Platform | Data Collected |
| -------- | -------------- |
| GitHub | Star counts |
## Key Metrics
### Adoption Health Score
A composite score from 0 to 100 that summarizes your overall adoption health at a glance. The score is calculated from four weighted components:
| Component | Weight | What It Measures |
| -------------------- | --------- | --------------------------------------------------- |
| Download Growth | 35 points | Recent download trend compared to the prior period |
| Market Share Trend | 25 points | Whether your share of total downloads is growing |
| Star Growth | 20 points | GitHub stars growth over the selected time range |
| Competitive Position | 20 points | Your ranking among tracked competitors by downloads |
The health score is color-coded:
* **70-100** (green) - Excellent
* **55-69** (yellow) - Good
* **40-54** (orange) - Needs Attention
* **Below 40** (red) - Critical
### Summary Stats
Four key stats displayed prominently on the dashboard:
* **Your Downloads** - 4-week average weekly downloads for your primary package
* **Your Market Share** - Your percentage of total tracked downloads
* **Your Rank** - Your position among all tracked packages
* **Growth Rate** - 3-month download growth percentage
### Competitor Movement
A section highlighting what changed in the last 30 days:
* Your market share change (up or down)
* Your rank change
* The fastest-growing competitor and their growth rate
* Your closest competitor and the download gap
## How It Works
Adoption Metrics uses the tracked URLs you have already configured in your project's **Project Settings > Brands**. There is no separate configuration step.
1. You configure tracked URLs in your project's **Brands** tab
2. Tracked URLs with type **GitHub repository** or **package registry** automatically feed into Adoption Metrics
3. DevTune collects data from each registry daily
4. The dashboard displays trends, market share, and competitive positioning
Data collection runs nightly. When you first add a new package, DevTune backfills up to one year of historical download data so your charts are immediately useful.
## Getting Started
1. **[Set Up Tracked URLs](/search-tracking/domains)** - Add GitHub repositories and package registry URLs inside the Brands tab
2. **[View the Dashboard](/adoption-tracking/dashboard)** - Explore your adoption metrics and competitive positioning
## Next Steps
* **[Adoption Dashboard](/adoption-tracking/dashboard)** - Understand each section of the dashboard
* **[Tracked URLs](/search-tracking/domains)** - Configure the package and repository URLs that feed adoption data
* **[AI Search](/search-tracking/overview)** - Learn about the visibility data that correlates with adoption
# Custom agents
Source: https://docs.devtune.ai/agents/custom-agents
Create a project agent with your own instructions, safe data tools, reviewable output, model, and schedule.
Custom agents let you define a repeatable job around your project data while keeping the same review-first boundary as the built-in roster.
## Create an agent
1. Open a project and select **Agents**
2. Select the **Custom** filter
3. Select **Create an agent**
4. Complete the **Agent configuration**
5. Select **Save agent**
You need the project management permission to create or edit an agent.
## Configure the job
Provide:
* **Name** — the label shown in the Agents hub and run history
* **One-sentence description** — what the agent does
* **Instructions** — the boundaries, priorities, and expected method for the job
* **Quick actions** — reusable prompts people can select when starting a run
Add at least one quick action. You can add up to six.
Write instructions as a stable job definition. Put one-off scope, such as a page or date range, into the run instruction instead.
## Choose tool access
The dialog separates tools by effect:
* **Read** tools let the agent inspect selected project data such as pages, search performance, traffic, citations, audit findings, guard rails, owned content, actions, and measured outcomes.
* **Draft** tools choose the one reviewable output the agent can create: a report, content brief, or action.
Select only the data needed for the job. A custom agent must have exactly one draft output type.
Custom agents cannot publish or change live content. They can read the
selected project data and create one kind of draft for review.
## Choose a model and schedule
The **Model** picker shows only models available to the account and includes each model's credit multiplier band.
Turn on **Schedule** in the agent configuration to use the daily shortcut at a selected time. Delivery is fixed to **In app**, and every scheduled output still waits for review.
The separate **Schedule** dialog supports daily, weekly, and monthly cadences for both custom and built-in agents.
## Edit a custom agent
Open the **Custom** filter and select **Edit** on the agent. You can update its description, instructions, quick actions, tool access, model, and daily schedule shortcut. Use the separate **Schedule** dialog to choose any supported cadence. Saved changes apply to future runs; existing run history remains available.
## Next steps
* [Run and review agents](/agents/overview)
* [Choose models and understand credits](/agents/models-and-credits)
# Agent models and credits
Source: https://docs.devtune.ai/agents/models-and-credits
Choose an agent model, read multiplier bands and run estimates, and understand credit reservation and settlement.
Every agent run uses a selected model and consumes credits based on measured model usage. The model picker shows a multiplier band as a quick relative-cost guide; the run estimate and final transaction use measured history and actual usage.
## Model picker
The **Model** picker appears when you start or schedule a built-in agent and when you create a custom agent. It shows only models that are available to your account.
The model catalog assigns these bands:
| Band | Models |
| -------- | ---------------------------------------------------------- |
| **0.5x** | GPT-5.6 Luna, Kimi K2.6 |
| **1x** | Claude Sonnet 4.6, Claude Sonnet 5, GPT-5.6 Terra, Kimi K3 |
| **2x** | Claude Opus 5, GPT-5.6 Sol |
| **4x** | Claude Fable 5 |
A band compares the model's representative input/output cost with the 1x reference. It is not a fixed charge and does not mean every 2x run costs exactly twice a particular 1x run. Prompt size, output length, tool work, and cached tokens affect the final amount.
## Estimated per run
When the same agent and model have completed measured runs, DevTune shows **Estimated per run** from the 75th percentile of up to 20 recent positive-usage runs. The dialog states how many runs form the estimate's basis.
When there is no measured history, the dialog shows **Credit estimate unavailable**. DevTune reserves one credit to protect the shared balance, then replaces that pending amount with the final measured cost after completion.
Changing the model changes the estimate because history is kept per agent and model.
## Estimated monthly
The schedule dialog also shows **Estimated monthly** when a per-run estimate exists:
* Daily schedules use 30 runs per display month
* Weekly schedules use `30 ÷ 7` runs per display month
* Monthly schedules use one run per display month
This is planning guidance, not a spending cap. Actual scheduled-run usage settles separately for every run.
## Balance checks and final cost
Before a run starts, DevTune reserves the estimated amount. If no estimate exists, it uses the one-credit first-run reservation. The run is blocked when the available account balance cannot cover that reservation.
After the run finishes:
* The final credit cost is calculated from measured model usage
* Any unused reservation returns to the account balance
* Additional usage is debited from the remaining balance when available
* The **Transactions** ledger replaces the pending estimate with the final amount
If measured usage exceeds the reservation and the remaining balance cannot cover
the full overage, DevTune debits only the available balance. The transaction
shows the credits actually charged, while settlement metadata records the unpaid
measured usage as `credit_micros_shortfall`. The balance never becomes negative,
and the shortfall is not carried forward or charged later.
Runs already in progress continue if the account later reaches zero credits. New runs remain blocked until credits become available.
Credits are one account-wide pool shared by agent runs and content workflows. Monthly allowance credits expire at the next billing anniversary; purchased credit packs do not expire. Spending uses expiring allowance credits before purchased credits.
## Next steps
* [Run and schedule agents](/agents/overview)
* [Review credit transactions](/account-billing/credit-transactions)
* [Manage Account & Billing](/account-billing/overview)
# DevTune Agents
Source: https://docs.devtune.ai/agents/overview
Run project-scoped agents, review their draft outputs, schedule repeat work, and follow run history.
**Agents** investigate your project data and produce reports, content briefs, or actions for review. They can read only their listed project tools, and every output stays a draft until a person approves or keeps it.
## Open Agents
1. Open a project
2. Select **Agents** in the project sidebar
3. Use **Grid view** or **List view** to browse the roster
You need the project management permission to start runs, change schedules, review outputs, or create custom agents.
## Agent roster
Each agent has one focused job and shows the project tools it can read and the draft type it delivers.
| Agent | Job |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Search Performance Analyst** | Explains weekly SEO and AEO movement and shows which search, traffic, page, and citation sources covered the report. |
| **Technical Auditor** | Explains current technical health as a baseline or compares two named audits, backed by page evidence and guard rails. |
| **Page Citability Improver** | Finds the highest-value page with citability problems and delivers a step-by-step improvement brief. |
| **404-Demand Triager** | Turns credible missing-page demand clusters into actions and states when traffic evidence is unavailable. |
| **Competitor Citation Analyst** | Finds AI answers that cite competitors or third parties for questions you should own and suggests content to compete for the citation. |
| **Brand Representation Auditor** | Checks AI descriptions against your product context and flags claims that are wrong, stale, or missing. |
| **Content Decay Detector** | Finds pages losing clicks, impressions, or citations and prioritizes refresh candidates. |
| **Question Coverage Planner** | Finds audience questions with no page to answer them and creates a brief for the largest gap. |
| **AI Crawler Access Sentinel** | Checks whether AI crawlers can reach and fetch your content and flags blocks, errors, and `llms.txt` gaps. |
| **Docs Consistency Checker** | Finds pages that contradict your product context or each other. |
| **New Page Citability Reviewer** | Reviews recently discovered pages against citability factors and briefs the fixes. |
| **Competitive Movement Digest** | Summarizes competitor visibility movement across tracked prompts and where you gained or lost ground. |
The visible roster and model choices can depend on the agent features configured for your account.
## Start a run
1. Select **Run** on an agent
2. Choose a **Model**
3. Review **Estimated per run** when history is available
4. Optionally choose a quick action or enter a focus instruction
5. Select **Start run**
DevTune checks the account credit balance before queueing. If recent completed runs exist for the same agent and model, the dialog estimates the next run from that history. The first completed run provides the first measured estimate.
The run detail shows the run log, tool steps, saved artifacts, model, trigger, timestamps, duration, and output. Status can move through **Queued**, **Provisioning**, **Running**, and **Polling** before reaching **Ready for review** or a terminal error state.
## Review the output
An agent output does not publish content or change your live site.
* Approve an action to select **Add to Actions**
* Approve a content brief to select **Send to Actions**
* Keep a report to retain it with the run
* Select **Dismiss** when you do not want the draft
After a draft is ready, use **Follow-up** to ask for a revision or next step. Each follow-up starts a separate run in the same run thread, grounded in the preceding output, and consumes credits like any other run.
## Schedule repeat runs
Select **Schedule** on an agent to configure:
* **Daily**, **Weekly**, or **Monthly** cadence
* Time and, when applicable, weekday or day of month
* Model used by scheduled runs
* Estimated monthly credits when enough history exists
Scheduled runs enter the same run history and review flow as manual runs. Their outputs still wait for review.
## Run history
**Run history** combines runs across the project. Filter it by agent, then select a row to inspect its log and output. The history distinguishes manual, scheduled, and follow-up triggers and shows usage recorded for each run.
## Next steps
* [Create a custom agent](/agents/custom-agents)
* [Choose models and understand credits](/agents/models-and-credits)
* [Review credit transactions](/account-billing/credit-transactions)
# AI Demand Dashboard
Source: https://docs.devtune.ai/ai-traffic/dashboard
Navigate the DevTune AI Demand dashboard to interpret retrieval evidence and the undercounted visible tail of AI referrals and conversions.
The AI Demand dashboard shows what AI systems and their users do with your site. Retrieval and citation evidence lead the story; referral sessions and conversions are the undercounted visible tail.
## Accessing the Dashboard
1. Select your project from the account home page
2. In the sidebar, open **AI Demand**
3. Review the dashboard
## Domain Filter
If your tracking snippet is installed on multiple websites or subdomains, a domain filter dropdown appears at the top of the dashboard. Select a specific domain to filter all charts and stats, or leave it on "All" to see aggregate data.
## Summary Stats
Four cards at the top provide an overview of your AI traffic:
### Total Traffic
The total number of events and unique sessions recorded across all traffic types. This is the sum of bot, referral, and other traffic.
### Bot Crawls
The number of events and unique sessions identified as AI bot crawlers (GPTBot, ClaudeBot, PerplexityBot, etc.). Higher bot crawl activity indicates more AI platforms are actively indexing your content.
### AI Referrals
The number of events and unique sessions attributed to an AI platform (ChatGPT, Claude, Perplexity, Gemini, Copilot). This is the visible referral tail, not the full measure of AI-driven demand.
### Other Traffic
All remaining traffic that is not classified as AI bot or AI referral. This provides context for the relative volume of AI traffic compared to your overall traffic.
## Traffic Trends Chart
A line chart showing daily traffic volume over time. Four tabs let you switch between views:
### All Traffic
Shows three lines for bot, referral, and other traffic, letting you compare their relative volumes and trends over time.
### Bot Traffic
Shows individual lines for each AI platform's bot activity. Use this to see which platforms crawl your site most frequently and how crawl patterns change over time.
### Referral Traffic
Shows individual lines for each AI platform's visible referral traffic. This reveals which platforms have attributable visits and whether that visible volume is growing.
### Other Traffic
Shows per-platform breakdown of other (non-AI) traffic.
Each view has an interactive legend. Click a platform name to show or hide its line on the chart. Hover over any data point to see exact counts.
## Platform Breakdown Chart
A horizontal bar chart showing traffic volume by AI platform. Tabs let you filter by traffic type (All, Bot, Referral, Other).
In the **All** view, bars are color-coded and stacked to show the proportion of bot versus visible referral traffic from each platform. This helps you compare attributable visits with crawler activity without treating referrals as the full measure of AI-driven demand.
Platforms displayed include:
| Platform | Identifier |
| ---------- | ------------------------- |
| OpenAI | ChatGPT, GPTBot |
| Anthropic | Claude, ClaudeBot |
| Perplexity | Perplexity, PerplexityBot |
| Google | Gemini, Google-Extended |
| Microsoft | Copilot |
| ByteDance | Bytespider |
| Meta | Meta-ExternalAgent |
## Top Pages Table
A sortable table showing the top 10 pages on your site by AI traffic. Columns include:
| Column | Description |
| ------------ | --------------------------------------------- |
| Page | The page path (e.g., `/docs/getting-started`) |
| Bot Crawls | Number of bot visits to this page |
| AI Referrals | Number of AI referral visits to this page |
| Total | Combined bot and referral visits |
Click any column header to sort ascending or descending. This helps you identify which pages AI platforms visit most and which pages receive the most AI-referred traffic.
## Top Pages Trends Chart
A multi-line chart showing the top 10 pages by traffic over the last 30 days (chart-specific window). Each page is a separate line, color-coded for easy identification.
Features:
* **Interactive legend** - Click page names to show or hide individual lines
* **Exclude Other toggle** - Switch on to show only bot and referral traffic, filtering out non-AI visits
This chart helps you identify trending pages and see how visible AI activity for specific content changes over time.
## Empty State
If no traffic data has been collected yet, the dashboard displays a setup prompt with a link to the AI Traffic Settings page. Install your tracking snippet and wait a few minutes for data to appear.
## Dashboard Data Range
The dashboard defaults to the last 90 days of data for most charts and summary stats, keeping the default view focused on recent activity. Some charts use a shorter, fixed window, such as the Top Pages Trends chart's 30-day window for recent page-level activity.
## Best Practices
### Monitor Bot Crawl Patterns
Track which AI bots crawl your site most frequently. If important content pages are not being crawled, review your `robots.txt` to ensure AI bots are not blocked from accessing key pages.
### Track Referral Growth
AI referral traffic is a lagging signal that some AI-driven visitors reached your site through attributable links. Growth in visible referrals can support the wider retrieval and visibility picture, but it does not measure total AI-driven demand.
### Pair with AI Search
Use AI Demand alongside AI Search to connect retrieval evidence with its visible downstream tail:
* **AI Search** shows whether AI platforms mention and cite your content in their responses
* **AI Demand** shows what AI systems retrieve and the referral sessions and conversions that can be attributed
AI referrals are systematically undercounted because most AI-driven visitors arrive as direct traffic. Treat referrals and conversions as lagging, visible evidence rather than a complete linear funnel.
### Review Top Pages
The Top Pages data shows which content has the most visible AI activity. Use this to:
* Identify content with the most visible AI activity
* Understand which types of content attract the most AI-referred visitors
* Prioritize content updates for pages that receive heavy AI traffic
## Troubleshooting
### No Data Appearing
* Verify the tracking snippet is installed correctly (check page source)
* Confirm tracking is enabled on the AI Traffic Settings page
* Check that ad blockers are not blocking requests (set up a proxy if needed)
* Wait a few minutes for initial data to appear
### Low Bot Traffic
* Check your `robots.txt` file for rules that might block AI crawlers
* AI bot crawling frequency varies by platform and is not under your control
### Low Referral Traffic
* Low referral traffic does not measure total AI-driven demand because most AI-driven visitors arrive as direct traffic
* Review your AI Search data to see if your presence rate is high but referrals are low
* Consider improving your content to be more actionable, encouraging users to visit your site
## Next Steps
* **[AI Traffic Setup](/ai-traffic/setup)** - Install or update your tracking sensor
* **[AI Demand Overview](/ai-traffic/overview)** - Understand what gets tracked and why
* **[AI Search](/search-tracking/overview)** - Monitor your visibility in AI search results
* **[Search Analytics](/analytics/search-analytics)** - Analyze your AI visibility trends
# Direct traffic
Source: https://docs.devtune.ai/ai-traffic/direct-traffic
Read the GA4 direct-traffic chart and understand when DevTune marks a change as AI-correlated lift.
The **Direct traffic** block in AI Demand compares GA4 direct sessions with a baseline for pages DevTune can measure. It highlights changes that line up with AI answer exposure without claiming that AI caused or owns those sessions.
## Open the Direct traffic view
1. Open a project
2. Select **AI Demand** in the project sidebar
3. Open **Overview**
4. Scroll to **Direct traffic**
The block requires connected GA4 data. Its comparison also needs enough Search Console and AI-answer coverage to evaluate the same page and time window.
## Read the chart
The chart keeps the verifiable GA4 total separate from the pages used for the comparison:
* **GA4 full direct total** bars show all direct sessions that GA4 reports for the project.
* **Measured-page actual** shows the daily equivalent of direct sessions for pages with complete comparison data.
* **Measured-page baseline** shows the same measured pages against their own recent baseline.
* A shaded **AI-correlated lift** span marks a window where all three correlation checks passed.
The lines may sit below the bars because the full GA4 total can include streams, hosts, or landing paths that are outside the measured-page population. Compare the two lines with each other. Do not treat the gap between a line and the bars as lift.
The population note below the chart tells you how many pages contributed to the lines on the latest date. A smaller population means the comparison covers less of the full GA4 total.
## How AI-correlated lift is evaluated
DevTune evaluates trailing seven-day windows. A window is marked **AI-correlated lift** only when all three legs hold:
1. **Direct traffic rose materially.** The measured pages are at least 10 sessions above baseline and at least 125% of baseline. DevTune looks at the four preceding seven-day windows and takes the median of those with enough historical coverage. Two, three, or all four can contribute; uncovered windows are left out. If fewer than two are available, the current window reads as **Unmeasured** instead of receiving a lift classification.
2. **AI answer exposure held.** The page had at least one citation or at least five answer fetches, and the qualifying signal did not fall by more than 25% from the prior window.
3. **Another measured channel did not explain the rise.** Search Console clicks, paid sessions, and non-AI referral sessions are checked against the direct-session increase. A channel rules out the AI-correlated label when it grew by at least 10% and by enough sessions to match at least 25% of the direct lift.
Citations take precedence over answer fetches when both are fully measured. Training crawls and visible AI referrals do not qualify the answer-exposure leg.
**AI-correlated** means the signals moved together under these checks. It does
not attribute direct sessions to AI, identify an AI platform, or prove
causation.
## Inspect a page-level result
Open **Audit → Pages**, then select a page to open its inspector. The **Direct traffic** section shows one of five states:
* **AI-correlated lift** — all three legs passed, with the measured values shown.
* **Unexplained lift** — direct traffic rose materially, but AI activity did not qualify.
* **Other-channel lift** — another measured channel grew enough to match the increase.
* **Baseline** — no material lift was detected.
* **Unmeasured** — GA4, Search Console, or AI-evidence coverage was incomplete.
An **AI-correlated traffic lift** item can also appear under **Needs attention** after the result persists across two non-overlapping seven-day windows in one uninterrupted episode.
## Why a highlighted span can disappear
The baseline adapts. When a higher traffic level persists, it becomes part of the recent baseline and the **AI-correlated lift** highlight can fade. The label detects the onset of a change; it is not a permanent attribution label.
## Next steps
* [Use Audit to inspect page evidence](/audit/overview)
* [Review AI Demand](/ai-traffic/dashboard)
* [Connect traffic data](/ai-traffic/setup)
# AI Demand Overview
Source: https://docs.devtune.ai/ai-traffic/overview
See what AI systems retrieve and cite, then measure the undercounted visible tail of referral sessions and conversions.
AI Demand shows what AI systems and their users do with your site. It leads with evidence of what AI systems crawl, retrieve, and cite, then shows the visible referral and conversion tail from platforms like ChatGPT, Claude, Perplexity, and Gemini.
## What AI Demand Tracks
AI Demand answers two questions:
1. **What are AI systems retrieving and citing?** - Detects crawlers and answer fetchers such as GPTBot, ClaudeBot, and PerplexityBot, alongside citation evidence from AI Search.
2. **What visible human activity follows?** - Tracks attributable referral sessions and conversions without treating them as the full measure of AI-driven demand.
AI referrals are systematically undercounted because most AI-driven visitors arrive as direct traffic. Referral and conversion metrics are the visible tail of AI demand, not a complete linear funnel.
You install a lightweight JavaScript snippet on your website. DevTune classifies each visit server-side and presents the data in a dashboard with trends, platform breakdowns, and top pages.
## Why AI Demand Matters
### AI Platforms Are a Growing Traffic Source
As more users rely on AI assistants to find information and products, the traffic they send to websites is becoming a meaningful channel. Understanding this traffic helps you:
* **Measure retrieval and visibility** - See which content AI systems fetch and cite before looking at downstream activity
* **Track AI bot crawling** - Know which AI platforms are indexing your content, how frequently, and which pages they visit most
* **Interpret the visible tail** - Pair AI Demand with AI Search while treating attributed referrals and conversions as an undercounted fraction
### Beyond Traditional Analytics
Standard analytics tools like Google Analytics do not break down AI bot traffic or AI referral traffic in useful ways. AI Demand is purpose-built to:
* Distinguish AI bots from regular crawlers
* Identify referral traffic specifically from AI conversation platforms
* Detect AI-sourced visits via `utm_source` parameters
* Show trends and breakdowns by AI platform
## Plan Requirements
AI Demand is available on plans that include the AI traffic entitlement.
## What Gets Detected
### Bot Crawlers
DevTune detects AI bot crawlers by their user-agent strings:
| Bot | Platform |
| ----------------------------------- | ---------- |
| GPTBot, ChatGPT-User, OAI-SearchBot | OpenAI |
| ClaudeBot, Claude-Web | Anthropic |
| PerplexityBot | Perplexity |
| Google-Extended | Google |
| Bytespider | ByteDance |
| Meta-ExternalAgent | Meta |
### AI Referral Traffic
DevTune detects visitors arriving from AI platforms by checking the referrer URL:
| Referrer | Platform |
| ---------------------------- | ------------------- |
| chat.openai.com, chatgpt.com | OpenAI (ChatGPT) |
| claude.ai | Anthropic (Claude) |
| perplexity.ai | Perplexity |
| gemini.google.com | Google (Gemini) |
| copilot.microsoft.com | Microsoft (Copilot) |
### UTM Source Detection
DevTune also checks the `utm_source` query parameter for AI platform identifiers (e.g., `chatgpt`, `claude`, `perplexity`, `gemini`, `copilot`). This catches traffic from AI platforms that include UTM parameters in their outbound links.
### Traffic Classification
Every visit is classified into one of three types:
* **Bot** - An AI crawler indexing your content
* **Referral** - A human visitor arriving from an AI platform
* **Other** - Regular traffic (not AI-sourced)
Classification happens entirely server-side. The tracking snippet sends raw signals (user agent, referrer, page URL) and DevTune handles all detection logic. This means detection rules are updated centrally without requiring snippet changes on your website.
## How It Works
1. You add a JavaScript snippet to your website (a single `
```
## Enable or Disable Tracking
On the Project Settings **AI Traffic** tab, use the toggle switch to enable or disable tracking at any time. When disabled, incoming events are rejected and no new data is recorded.
## Rate Limits
Each tracking snippet is rate-limited to **1,000 requests per minute**. This is enough for most sites. If your site exceeds this limit, excess requests are silently dropped.
## Crawler Sensor Capabilities
AI crawlers and answer fetchers often do not run JavaScript, so DevTune also supports server-side crawler sensors. Use one server-side crawler sensor per hostname to avoid double-counting.
| Capability | Cloudflare pull | Edge middleware |
| ------------ | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Best for | Hostnames already proxied by Cloudflare, including docs or static hosts that cannot run app middleware. | Vercel, Next.js, or self-hosted apps where request middleware can run. |
| Setup | Zone ID, readonly API token, and an orange-cloud proxied hostname. | Server-side ingest key plus `@devtune/ai-traffic` in your proxy or middleware. |
| Data flow | DevTune pulls hourly Cloudflare analytics buckets. | Your edge code pushes matched AI bot requests asynchronously. |
| Freshness | Hourly sync after Cloudflare analytics are available. | Near real-time push into DevTune's ingest queue. |
| Granularity | Hourly aggregate buckets by page, user agent, bot class, and status. | One event per matched request with URL, path, user agent, bot class, and optional status. |
| History | Can backfill the recent Cloudflare analytics window available to the zone. | Starts collecting only after middleware is installed and deployed. |
| Status codes | Real edge status classes for proxied traffic, including 404s. | Known for redirects and denials returned by middleware. Normal page responses are status unknown unless you add route wrappers or known 404 path patterns. |
| Coverage | Only traffic that passes through the orange-cloud hostname. | Only routes reached by your app middleware. |
| Avoid | Using Cloudflare and middleware on the same hostname. | Double-proxying an app through Cloudflare just to collect traffic. |
Recommended split:
* Use **Cloudflare pull** for docs, marketing, or static hostnames that already sit behind Cloudflare.
* Use **edge middleware** for Vercel, Next.js, and app hostnames where you do not want a Cloudflare-to-app double proxy.
* Keep a hostname on one crawler sensor at a time. If you move a hostname from Cloudflare pull to middleware, remove or pause the Cloudflare hostname connection.
## Edge Middleware Setup
Install `@devtune/ai-traffic`, keep your ingest key in a server-side environment variable, and call the package only for likely machine user agents. Keep the prefilter broad enough for future crawler and fetcher names; the package still performs the authoritative registry match before ingesting an event, but the cheap prefilter keeps normal browser traffic out of the middleware tracking path. Set `batchSize: 1`, `flushIntervalMs: 0`, and `waitUntilRegistryRefresh: false` in middleware so background ingest work is scheduled immediately, and hourly registry refreshes do not extend middleware `waitUntil` duration.
```typescript theme={null}
// proxy.ts (Next.js 16; use middleware.ts/middleware() on older Next.js)
import { createDevTuneAiTraffic } from '@devtune/ai-traffic';
import {
NextResponse,
type NextFetchEvent,
type NextRequest,
} from 'next/server';
const aiTraffic = createDevTuneAiTraffic({
ingestKey: process.env.DEVTUNE_AI_TRAFFIC_INGEST_KEY!,
batchSize: 1,
defaultStatus: null,
flushIntervalMs: 0,
waitUntilRegistryRefresh: false,
});
const aiTrafficMachineUserAgentHints = [
'bot',
'crawler',
'spider',
'fetch',
'agent',
'gpt',
'claude',
'anthropic',
'perplexity',
'openai',
'notebooklm',
'google-extended',
'bytespider',
'meta-external',
'-ai',
'ai-',
];
function isLikelyMachineTraffic(request: NextRequest) {
const userAgent = request.headers.get('user-agent')?.toLowerCase();
return aiTrafficMachineUserAgentHints.some((hint) =>
userAgent?.includes(hint),
);
}
export function proxy(request: NextRequest, event: NextFetchEvent) {
const response = NextResponse.next();
if (isLikelyMachineTraffic(request)) {
aiTraffic.trackRequest(request, event, null);
}
return response;
}
```
When your middleware returns a redirect, denial, or custom response, pass `response.status` instead of `null`. For normal pass-through page requests, keep `null` because the middleware cannot observe the final page status.
## Proxy Setup
You can proxy the tracking endpoint through your own domain when you need first-party routing for your deployment setup. Teams should still honor consent requirements and local privacy rules before collecting traffic data.
### How It Works
Instead of the snippet sending data to `https://devtune.ai/api/v1/llm-traffic/collect`, you configure a reverse proxy, so requests go to a path on your own domain.
### Vercel / Next.js
Add a rewrite to `next.config.ts`:
```javascript theme={null}
async rewrites() {
return [
{
source: '/dt/:path*',
destination:
'https://devtune.ai/api/v1/llm-traffic/:path*',
},
];
}
```
### Netlify
Add to `netlify.toml`:
```toml theme={null}
[[redirects]]
from = "/dt/*"
to = "https://devtune.ai/api/v1/llm-traffic/:splat"
status = 200
force = true
```
### Cloudflare
Create a redirect rule or Worker that proxies `/dt/*` to `https://devtune.ai/api/v1/llm-traffic/*`.
### nginx
```nginx theme={null}
location /dt/ {
proxy_pass https://devtune.ai/api/v1/llm-traffic/;
proxy_set_header Host devtune.ai;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
}
```
After setting up the proxy, update the beacon URL in your snippet to use the first-party path.
## Multi-Site Tracking
You can use the same tracking snippet across multiple websites or subdomains. The dashboard automatically detects distinct domains and provides a domain filter so you can view traffic for each site individually or in aggregate.
## Verifying Installation
After installing the snippet:
1. Visit your website in a browser
2. Open the DevTune AI Demand dashboard
3. You should see traffic appearing within a few minutes
If no data appears, check:
* The snippet is present in your page source
* The snippet key matches the one shown in Project Settings
* Ad blockers are not blocking the request
* Tracking is enabled on the AI Traffic tab
## Next Steps
* **[AI Demand Dashboard](/ai-traffic/dashboard)** - Explore your demand data
* **[AI Demand Overview](/ai-traffic/overview)** - Learn what gets tracked and why
# Analytics Overview
Source: https://docs.devtune.ai/analytics/overview
Explore DevTune's analytics views to turn AI Search tracking runs into patterns: where your brand appears, which sources platforms cite, and weak topics.
DevTune's analytics views turn raw search tracking runs into patterns you can act on. Use them to understand where your brand appears, what kinds of sources AI platforms prefer, and which topics need work.
## Plan Requirements
Analytics features are available on paid plans that include AI Search.
## Analytics Views
### Search Analytics
Search Analytics is the trend and breakdown view for your project. It combines shared filters with a curated chart set:
* **Domain Position vs Visibility** - Bubble chart showing which domains are cited most, how often they appear, and how high they rank
* **Presence Rates Over Time** - Time series for overall primary presence plus source-specific lines for Docs, Blog, GitHub, Home, Package Registry, and Other
* **Citations by Type** - Breakdown of citations by domain type such as docs, blog, GitHub, package, tutorial, and other content categories
* **Citations by Source Vertical** - Breakdown of citation sources such as editorial, commercial, forum, documentation, and social
* **Topic Performance Rankings** - Ranked topic chart showing where citations land across positions 1-3, 4-10, and 11+
Shared controls let you filter the page by:
* **Date range**
* **Topic**
* **Platform**
* **Time grouping** (`daily`, `weekly`, or `monthly`)
Several charts also include their own tabs for switching between **Primary**, **Competitors**, **Primary + Competitors**, or **All Sources**, depending on the chart.
**[Learn more about Search Analytics](/analytics/search-analytics)**
## Accessing Analytics
Navigate to analytics through your project sidebar:
1. Select your project from the account home page
2. In the sidebar, open **Signals**
3. Select **AI Search** and open the **Analytics** tab for charts and trends
## Analytics Best Practices
### Start with Search Analytics
Use Search Analytics when you want to answer questions like:
* Which owned domains are winning citations right now?
* Are docs, blog, GitHub, or package pages driving more presence?
* Which topics produce the strongest citation positions?
* Are competitors clustering around the same prompts and topics?
## Getting Started
1. **[Search Analytics](/analytics/search-analytics)** - Explore visibility data and trends
# AI Search Analytics
Source: https://docs.devtune.ai/analytics/search-analytics
Analyze AI Search visibility trends, platform performance, top citations, and competitive positioning with shared filters and focused breakdown charts.
AI Search Analytics is the main trend and breakdown view for AI Search. It combines shared filters with a focused set of charts so you can understand where your brand appears, which sources are cited, and which topics deserve attention.
## Accessing Search Analytics
1. Navigate to your project
2. Open **AI Search**
3. Select the **Analytics** tab
## Shared Filters
Every chart on the page uses the same top-level filters:
* **Date range** - Limit the analysis window
* **Topic** - Focus the page on a single topic group
* **Platform** - Filter to a single AI platform
* **Time grouping** - Switch between `daily`, `weekly`, and `monthly`
Some charts also have their own tabs for switching between **Primary**, **Competitors**, **Primary + Competitors**, or **All Sources**, depending on the chart.
## Charts on the Page
### Domain Position vs Visibility
This bubble chart shows how cited domains compare on three dimensions at once:
* **X-axis** - Unique responses where the domain appears
* **Y-axis** - Average citation position, with higher-ranked positions appearing higher on the chart
* **Bubble size** - Citation share
Use the **Group by Brand** toggle to collapse domains into brand-level groupings, or leave it off to inspect individual domains.
This chart is useful for seeing:
* which owned domains dominate visibility
* which competitor domains are cited often
* which domains appear often but at weaker positions
### Presence Rates Over Time
This chart tracks primary presence over time across multiple source-specific series:
* **Overall**
* **Docs**
* **Blog**
* **GitHub**
* **Home**
* **Package Registry**
* **Other**
Use it to answer questions like:
* Is overall presence rising or falling?
* Are docs and blog pulling their weight?
* Are GitHub or package pages becoming more important over time?
* Did a source category drop after a content or classification change?
You can toggle individual series on and off from the interactive legend.
### Citations by Type
This donut chart groups citations by **domain type**:
* **Docs**
* **Blog**
* **GitHub**
* **Home**
* **Package Registry**
* **Other**
Use the chart tabs to compare:
* **Primary**
* **Competitors**
* **Primary + Competitors**
This helps you understand what kinds of content are winning citations in the current slice of data.
### Citations by Source Vertical
This donut chart groups citations by broader **source vertical** such as editorial, commercial, documentation, forum, social, blog, and other source classes.
It is useful for quickly understanding whether AI platforms are leaning on:
* owned or competitor properties
* editorial or reference content
* community or forum discussions
* commercial pages
### Topic Performance Rankings
This chart ranks topics by citation volume and splits each topic into three position bands:
* **Positions 1-3**
* **Positions 4-10**
* **Positions 11+**
Use the chart tabs to compare **Primary** and **Competitors**. Clicking a topic bar also applies that topic as a page filter so you can continue drilling into the rest of the dashboard.
## Common Analysis Scenarios
### Performance Review
Weekly or monthly review workflow:
1. Check **Presence Rates Over Time** for sustained movement in overall and source-specific visibility
2. Review **Domain Position vs Visibility** to see which domains are actually driving or losing citations
3. Use **Topic Performance Rankings** to find strong and weak content areas
4. Check **Citations by Type** and **Citations by Source Vertical** for shifts in source mix
### Problem Investigation
When visibility drops:
1. Narrow the page with the shared filters for date range, topic, or platform
2. Check whether the drop is broad or source-specific in **Presence Rates Over Time**
3. Use **Domain Position vs Visibility** to see whether the same domains still appear but at worse positions
4. Review prompts and citations directly if you need the underlying examples
### Opportunity Identification
Finding growth areas:
1. Look for topics where competitors dominate positions 1-3
2. Find source categories where your presence is flat or missing
3. Check whether strong topic performance is coming from the right domain types
4. Turn those gaps into content or domain coverage work
## Next Steps
* [**Citations**](/search-tracking/citations) - Detailed citation tracking
* [**Prompts**](/search-tracking/prompts) - Manage tracked search prompts
# API Authentication
Source: https://docs.devtune.ai/api-reference/authentication
Create project-scoped API keys, configure endpoint scopes, and authenticate DevTune REST API requests with the Authorization bearer header.
The DevTune API uses API keys for authentication. Each key is scoped to a single project and must be included in the `Authorization` header of every request.
Keys can either:
* keep the default **all scopes** access for that project
* or be narrowed to specific endpoint scopes such as `visibility.read`, `citations.read`, `competitive.read`, `adoption.read`, `traffic.read`, `tests.read`, `actions.read`, `actions.write`, `intelligence.read`, `webhooks.read`, `webhooks.write`, `pages.read`, `audit.read`, `outcomes.read`, `referrals.read`, `agents.read`, and `agents.run`
The ground-truth and managed-agent scopes are explicit grants. Existing keys are not expanded when these scopes are introduced; edit or replace a key and select the new scope before calling its REST endpoint or MCP tool.
## Creating an API Key
1. Navigate to your team account
2. Open **API Keys** in the account sidebar
3. Click **Create API Key**
4. Enter a name for the key (e.g., "CI/CD Pipeline" or "BI Dashboard")
5. Select the project the key should access
6. Click **Create API Key**
After creation, the full key is displayed **once**. Copy it immediately and store it securely. You will not be able to view the full key again.
## Key Format
API keys follow this format:
```
dtk_live_<64 hex characters>
```
For example: `dtk_live_a1b2c3d4e5f6...`
Only the first few characters (`dtk_live_a1b2...`) are stored as a prefix for identification in the dashboard.
## Using Your API Key
Include the key in the `Authorization` header with the `Bearer` prefix:
```bash theme={null}
curl -H "Authorization: Bearer dtk_live_your_key_here" \
"https://devtune.ai/api/v2/projects/YOUR_PROJECT_ID/visibility/summary"
```
### Example with JavaScript
```javascript theme={null}
const response = await fetch(
'https://devtune.ai/api/v2/projects/YOUR_PROJECT_ID/visibility/summary',
{
headers: {
Authorization: 'Bearer dtk_live_your_key_here',
},
},
);
const { data, meta } = await response.json();
```
### Example with Python
```python theme={null}
import requests
response = requests.get(
"https://devtune.ai/api/v2/projects/YOUR_PROJECT_ID/visibility/summary",
headers={"Authorization": "Bearer dtk_live_your_key_here"}
)
result = response.json()
print(result["data"])
```
## MCP OAuth Authentication
The REST API uses API keys. The DevTune MCP server also supports OAuth for MCP clients that can discover and complete an OAuth 2.1 flow.
For OAuth MCP connections, configure the server URL without a project ID:
```
https://devtune.ai/api/mcp
```
The MCP server advertises protected resource metadata at:
```
https://devtune.ai/.well-known/oauth-protected-resource/api/mcp
```
After browser sign-in, DevTune shows a project selector and stores that choice with the OAuth grant. Integration prerequisite: the OAuth access token must include a client identifier claim (`client_id`, `oauth_client_id`, or `azp`), or DevTune rejects MCP authentication. OAuth clients should use standard Supabase OAuth sign-in scopes rather than DevTune API key scopes. OAuth connections run as the signed-in DevTune user for the selected project. Project account members can use read tools. Users with DevTune management permission can also use write tools such as action brief generation.
## Key Security
* Keys are hashed with SHA-256 before storage. DevTune never stores the raw key.
* Each key is scoped to exactly one project. It cannot access data from other projects.
* Each key stores an explicit scope set. It can only call endpoints and MCP tools covered by those configured scopes.
* Requests with an invalid, expired, or revoked key receive a generic `401 Unauthorized` response.
* Requests with a valid key that lacks the required endpoint or MCP tool scope receive `403 Forbidden`, so permission errors stay distinct from authentication failures.
## CORS Support
The API supports Cross-Origin Resource Sharing (CORS) for browser-based integrations. Requests from any origin are accepted when a valid API key is provided.
## Revoking a Key
To revoke an API key:
1. Go to **API Keys** in the account sidebar
2. Find the key in the list
3. Click the revoke button (trash icon)
4. Confirm the revocation
Revoked keys stop working immediately. This action cannot be undone.
## Who Can Manage API Keys
Only team members with the **settings.manage** permission can create or revoke API keys.
## Related Documentation
* **[Rate Limits](/api-reference/rate-limits)** - Request limits by plan tier
* **[Error Handling](/api-reference/errors)** - Common authentication errors
# Create webhook subscription
Source: https://docs.devtune.ai/api-reference/create-webhook-subscription
/openapi.json post /projects/{projectId}/webhooks
Registers a new webhook subscription. Returns the subscription including the signing secret (only shown once). Requires the webhooks.write scope.
# Delete webhook subscription
Source: https://docs.devtune.ai/api-reference/delete-webhook-subscription
/openapi.json delete /projects/{projectId}/webhooks/{webhookId}
Deactivates a webhook subscription. Requires the webhooks.write scope.
# Detect intelligence anomalies
Source: https://docs.devtune.ai/api-reference/detect-intelligence-anomalies
/openapi.json get /projects/{projectId}/intelligence/anomalies
Detects unusual shifts in primary citations and presence rate using rolling baseline analysis.
# API Error Handling
Source: https://docs.devtune.ai/api-reference/errors
DevTune API HTTP status codes, structured JSON error response format, common error codes, retry guidance, and troubleshooting steps for failed requests.
The DevTune API uses standard HTTP status codes and returns structured JSON error responses.
## Error Response Format
All errors follow this structure:
```json theme={null}
{
"error": "error_code",
"message": "Human-readable description of the error.",
"status": 400
}
```
| Field | Description |
| --------- | ----------------------------------------------------------------- |
| `error` | Machine-readable error code (e.g., `unauthorized`, `bad_request`) |
| `message` | Human-readable explanation |
| `status` | HTTP status code |
## Error Codes
### 400 Bad Request
```json theme={null}
{
"error": "bad_request",
"message": "Invalid query parameters: ...",
"status": 400
}
```
**Cause:** One or more query parameters failed validation. The message includes details about which parameters are invalid.
**Fix:** Check the endpoint documentation for valid parameter values and formats.
***
### 401 Unauthorized
```json theme={null}
{
"error": "unauthorized",
"message": "Invalid or missing API key",
"status": 401
}
```
**Cause:** The `Authorization` header is missing, malformed, or contains an invalid key.
**Fix:** Ensure your request includes `Authorization: Bearer dtk_live_...` with a valid, active API key.
***
### 403 Forbidden
```json theme={null}
{
"error": "forbidden",
"message": "API access requires a Plus plan or higher",
"status": 403
}
```
**Cause:** Either your plan does not include API access, or the API key does not have access to the requested project.
**Fix:** Upgrade to a Plus plan or higher. If you already have a qualifying plan, verify the API key is scoped to the correct project.
> **Note:** A 403 can also occur when using a project-scoped API key to access a different project's resources.
***
### 404 Not Found
```json theme={null}
{
"error": "not_found",
"message": "The requested resource was not found",
"status": 404
}
```
**Cause:** The resource (project, webhook, etc.) does not exist or the API key does not have access to it.
**Fix:** Verify the resource ID in the URL. If using a project-scoped key, ensure the project ID matches the key's scope.
***
### 429 Too Many Requests
```json theme={null}
{
"error": "rate_limit_exceeded",
"message": "Rate limit exceeded. Please try again later.",
"status": 429
}
```
**Cause:** You've exceeded the rate limit for your plan tier.
**Fix:** Wait until the `X-RateLimit-Reset` timestamp (in the response headers) before retrying. See [Rate Limits](/api-reference/rate-limits) for details.
***
### 500 Internal Server Error
```json theme={null}
{
"error": "internal_error",
"message": "An unexpected error occurred",
"status": 500
}
```
**Cause:** Something went wrong on our end.
**Fix:** Retry after a short delay. If the error persists, contact support.
## Troubleshooting Tips
* **Getting 401 on every request?** Check that you're using the `Bearer` prefix: `Authorization: Bearer dtk_live_...`
* **Getting 403 with a valid key?** The project ID in the URL must match the project the key was created for.
* **Getting 400 on date parameters?** Dates must be in `YYYY-MM-DD` format (e.g., `2026-01-15`).
* **Getting 429 unexpectedly?** Rate limits are per-minute. If you're making many requests in a loop, add a short delay between calls.
## Related Documentation
* **[Authentication](/api-reference/authentication)** - API key setup
* **[Rate Limits](/api-reference/rate-limits)** - Limits by plan tier
# Generate action brief
Source: https://docs.devtune.ai/api-reference/generate-action-brief
/openapi.json post /projects/{projectId}/actions/{actionId}/brief
Queues or reuses command-center brief generation for the specified action and returns the current generation state.
# Get 404 Demand
Source: https://docs.devtune.ai/api-reference/get-404-demand
/openapi.json get /projects/{projectId}/traffic/404-demand
Returns project-scoped content-intent and suspected-noise 404 clusters from the current materializer window, including explicit degraded state and machine-traffic sensor coverage. When AI traffic ground truth is disabled, the endpoint returns 404 Resource not found.
# Get a managed-agent run
Source: https://docs.devtune.ai/api-reference/get-a-managed-agent-run
/openapi.json get /projects/{projectId}/agents/runs/{runId}
Returns run status and the bounded draft output artifact only after the run reaches a completed review state.
# Get action brief
Source: https://docs.devtune.ai/api-reference/get-action-brief
/openapi.json get /projects/{projectId}/actions/{actionId}/brief
Returns the stored brief status for an action together with the execution-ready markdown payload when a brief is ready.
# Get adoption metrics
Source: https://docs.devtune.ai/api-reference/get-adoption-metrics
/openapi.json get /projects/{projectId}/adoption/metrics
Returns npm downloads and GitHub stars trends for project domains.
# Get aggregate citation statistics
Source: https://docs.devtune.ai/api-reference/get-aggregate-citation-statistics
/openapi.json get /projects/{projectId}/citations/stats
Returns aggregate citation totals from the v2 citation stats rollup for a fixed 30 or 90 day window. Use top-pages and top-domains for citation lists.
# Get AI-correlated Direct lift
Source: https://docs.devtune.ai/api-reference/get-ai-correlated-direct-lift
/openapi.json get /projects/{projectId}/traffic/direct-lift
Returns GA4-true project Direct totals, measured-page actual and baseline daily equivalents, and resolver-owned page-window classifications for a fixed 7, 28, or 90 day request. AI-correlated lift is correlated evidence, never attributed traffic, and is never summed with measured referrals. Page details are capped while totals are uncapped. Direct-lift evaluation supports measured-page populations up to 5,000 pages; larger populations return 422 lift_population_too_large rather than partial aggregates. When AI traffic ground truth is disabled, the endpoint returns 404 Resource not found.
# Get Audit summary
Source: https://docs.devtune.ai/api-reference/get-audit-summary
/openapi.json get /projects/{projectId}/audit/summary
Returns completed domain Audit summaries, pillar scores, and the same fixed-window trend shown in the application.
# Get competitive positioning data
Source: https://docs.devtune.ai/api-reference/get-competitive-positioning-data
/openapi.json get /projects/{projectId}/competitive/position
Returns citation comparison between primary, competitor, and other sources over time for a fixed rolling window. The default includes only currently active project platforms.
# Get Google eligibility evidence
Source: https://docs.devtune.ai/api-reference/get-google-eligibility-evidence
/openapi.json get /projects/{projectId}/audit/eligibility
Returns resolver-derived URL Inspection eligibility dimensions, two-inspection confirmed transitions, and sitemap submission state for a fixed 7, 28, or 90 day window. Evidence is dated from successful measurements. Detail lists are capped while totals are not. When AI traffic ground truth is disabled, the endpoint returns 404 Resource not found.
# Get top citation domains
Source: https://docs.devtune.ai/api-reference/get-top-citation-domains
/openapi.json get /projects/{projectId}/citations/top-domains
Returns top citation domains for a fixed 30 or 90 day window.
# Get top citation pages
Source: https://docs.devtune.ai/api-reference/get-top-citation-pages
/openapi.json get /projects/{projectId}/citations/top-pages
Returns top citation pages for a fixed 30 or 90 day window.
# Get traffic by platform
Source: https://docs.devtune.ai/api-reference/get-traffic-by-platform
/openapi.json get /projects/{projectId}/traffic/platforms
Returns LLM traffic data grouped by AI platform with event counts and percentages.
# Get traffic summary
Source: https://docs.devtune.ai/api-reference/get-traffic-summary
/openapi.json get /projects/{projectId}/traffic/summary
Returns aggregate LLM traffic metrics and project-wide sensor state derived from current configuration, connections, and accepted measurements. The domain parameter filters traffic totals but not sensor state.
# Get visibility diff
Source: https://docs.devtune.ai/api-reference/get-visibility-diff
/openapi.json get /projects/{projectId}/visibility/diff
Compares the current visibility window with the previous same-length window.
# Get visibility summary metrics
Source: https://docs.devtune.ai/api-reference/get-visibility-summary-metrics
/openapi.json get /projects/{projectId}/visibility/summary
Returns share of voice, presence rate, brand mentions, and citation statistics. The default scope includes only platforms currently active for the project.
# Get what-works recommendations
Source: https://docs.devtune.ai/api-reference/get-what-works-recommendations
/openapi.json get /projects/{projectId}/intelligence/what-works
Returns channel-level learnings from completed actions whose target URLs were marked as interventions, crawled after completion, and correlated with outcome metrics. If there is not enough intervention data yet, the endpoint returns an explanatory emptyState with the missing requirements and current counts.
# List actions
Source: https://docs.devtune.ai/api-reference/list-actions
/openapi.json get /projects/{projectId}/actions/list
Returns the current actions workspace for a project. Active recommendations are ordered by portfolioRank, which follows the same expected customer-impact model used by the app and MCP.
# List AI referrals
Source: https://docs.devtune.ai/api-reference/list-ai-referrals
/openapi.json get /projects/{projectId}/traffic/referrals
Returns the AI-referral demand series and overview from the same Traffic rollups used by the application.
# List Audit findings
Source: https://docs.devtune.ai/api-reference/list-audit-findings
/openapi.json get /projects/{projectId}/audit/findings
Returns the bounded finding rollup used by the Audit surface. Arbitrary date ranges are not accepted. affectedUrls is a capped sample; affectedPageCount reports the uncapped population the audit measured, in the unit named by affectedScope, and is null when a finding covers no countable population.
# List content gaps
Source: https://docs.devtune.ai/api-reference/list-content-gaps
/openapi.json get /projects/{projectId}/content-gaps/list
Returns canonical content-gap signals from the Actions system. These are topic or prompt-cluster opportunities backed by command-center evidence; workflow fields such as opportunityScore, status, briefs, and interventions remain on the Actions endpoints.
# List managed-agent runs
Source: https://docs.devtune.ai/api-reference/list-managed-agent-runs
/openapi.json get /projects/{projectId}/agents/runs
Returns project-scoped managed-agent run status and definition display fields. Draft output is available only from the single-run endpoint after completion.
# List managed agents
Source: https://docs.devtune.ai/api-reference/list-managed-agents
/openapi.json get /projects/{projectId}/agents
Returns roster and active custom agents with display fields only.
# List measured outcomes
Source: https://docs.devtune.ai/api-reference/list-measured-outcomes
/openapi.json get /projects/{projectId}/outcomes/ledger
Returns the Outcomes ledger and scoreboard from their canonical rollups. Only the fixed 7, 28, 90, and 365 day windows are accepted.
# List page guard-rail findings
Source: https://docs.devtune.ai/api-reference/list-page-guard-rail-findings
/openapi.json get /projects/{projectId}/pages/guard-rails
Returns the same bounded page guard-rail rollup used by the Audit surface. Arbitrary date ranges are not accepted.
# List unified page metrics
Source: https://docs.devtune.ai/api-reference/list-unified-page-metrics
/openapi.json get /projects/{projectId}/pages/metrics
Returns the same unified Audit page rollup and summary shown in the application. Only the fixed 7, 28, and 90 day windows are accepted.
# List webhook subscriptions
Source: https://docs.devtune.ai/api-reference/list-webhook-subscriptions
/openapi.json get /projects/{projectId}/webhooks
Returns active webhook subscriptions for the project. Requires the webhooks.read scope.
# MCP Server
Source: https://docs.devtune.ai/api-reference/mcp-server
Connect Claude, Cursor, and other MCP-compatible coding agents to DevTune AI search visibility data with the Streamable HTTP Model Context Protocol server.
DevTune exposes a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server so that AI agents can query your AI search visibility data directly. This lets agents like Codex, Claude, Cursor, and other MCP-compatible tools access your metrics and data directly.
## Server URL
The server uses **Streamable HTTP** transport at:
```text theme={null}
https://devtune.ai/api/mcp
```
The MCP server supports two setup paths:
* **OAuth** for interactive tools like Codex
* **API key** for non-interactive agents, CI jobs, or clients without OAuth support
## Setup
### Codex
Codex users can install the DevTune plugin from the DevTune plugin marketplace:
```bash theme={null}
codex plugin marketplace add devtunehq/codex-plugins --ref main
```
After adding the marketplace:
1. Restart Codex
2. Open the plugin list
3. Install the DevTune plugin
4. Sign in when Codex opens the browser authorization flow
5. Select the DevTune project the plugin should access
Once authorized, ask Codex to use DevTune for visibility summaries, citations, competitive positioning, actions, traffic, adoption metrics, or content gaps.
### Other OAuth MCP Clients
Use this configuration when your MCP client supports OAuth:
```json theme={null}
{
"mcpServers": {
"devtune": {
"type": "streamable-http",
"url": "https://devtune.ai/api/mcp"
}
}
}
```
When your client prompts for authorization, sign in to DevTune, select a project, and approve access.
### API Key
Use API keys for non-interactive agents, CI jobs, or clients without OAuth support. Pass your key in the `Authorization` header:
```text theme={null}
Authorization: Bearer dtk_live_your_key_here
```
#### Claude Desktop
Add to your Claude Desktop config file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json theme={null}
{
"mcpServers": {
"devtune": {
"type": "streamable-http",
"url": "https://devtune.ai/api/mcp",
"headers": {
"Authorization": "Bearer dtk_live_YOUR_API_KEY_HERE"
}
}
}
}
```
#### Cursor
Open **Settings > MCP Servers > Add Server**, or edit `.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"devtune": {
"type": "streamable-http",
"url": "https://devtune.ai/api/mcp",
"headers": {
"Authorization": "Bearer dtk_live_YOUR_API_KEY_HERE"
}
}
}
}
```
#### Claude Code
```bash theme={null}
claude mcp add devtune \
--transport http \
https://devtune.ai/api/mcp \
--header "Authorization: Bearer dtk_live_YOUR_API_KEY_HERE"
```
## REST vs MCP
Use REST when you are building an app, job, warehouse sync, dashboard, or webhook consumer. Use MCP when an AI agent should inspect DevTune data and decide what to do next inside a workflow.
## Available Tools
| Category | Tool | Access | Description |
| --------------- | ---------------------------------- | ------ | ------------------------------------------------------------------------------------- |
| Overview | `devtune_get_visibility_summary` | Read | Share of voice, presence rate, brand awareness, and citation counts |
| Diagnostics | `devtune_get_competitive_position` | Read | Competitive positioning time series (daily/weekly/monthly) |
| Diagnostics | `devtune_get_citation_analysis` | Read | Backward-compatible alias for top citation pages |
| Diagnostics | `devtune_get_top_citation_pages` | Read | Cursor-paginated top citation pages with URL, domain, classification, and position |
| Diagnostics | `devtune_get_top_citation_domains` | Read | Cursor-paginated top citation domains with counts, unique URLs, and class totals |
| Diagnostics | `devtune_get_citation_stats` | Read | Aggregate citation stats for the selected 30- or 90-day window |
| Recommendations | `devtune_get_actions` | Read | Current actions workspace, including active recommendations and adopted backlog items |
| Execution | `devtune_get_action_brief` | Read | Stored brief status and execution-ready markdown for a specific action |
| Execution | `devtune_generate_action_brief` | Write | Queue or reuse command-center brief generation for a specific action |
| Diagnostics | `devtune_get_traffic_summary` | Read | LLM bot and referral traffic analytics |
| Ground truth | `devtune_get_404_demand` | Read | Project-scoped classified 404 Demand and sensor coverage |
| Diagnostics | `devtune_get_adoption_metrics` | Read | npm downloads and GitHub stars trends |
| Recommendations | `devtune_get_content_gaps` | Read | Canonical content-gap signals with `signalStrength`, component metrics, and evidence |
| Ground truth | `devtune_get_page_metrics` | Read | Unified page metrics from the Audit rollup |
| Ground truth | `devtune_get_page_guard_rails` | Read | Paginated page guard-rail classifications |
| Ground truth | `devtune_get_audit_summary` | Read | Completed Audit summaries, pillars, checks, and outcome trend |
| Ground truth | `devtune_get_audit_findings` | Read | Paginated Audit findings |
| Ground truth | `devtune_get_google_eligibility` | Read | Fixed-window Google eligibility dimensions, transitions, and sitemap submission state |
| Ground truth | `devtune_get_outcomes_ledger` | Read | Outcomes ledger and scoreboard |
| Ground truth | `devtune_get_ai_referrals` | Read | AI-referral landing-page demand and Traffic overview |
| Agents | `devtune_list_agents` | Read | Roster and custom-agent display fields |
| Agents | `devtune_list_agent_runs` | Read | Managed-agent run status, timing, usage, and identity |
| Agents | `devtune_get_agent_run` | Read | One run and its bounded draft artifact after completion |
| Agents | `devtune_run_agent` | Run | Trigger or reuse a metered manual run through the existing dispatch path |
Each windowed tool accepts only its documented fixed rolling windows and returns JSON data. Existing visibility tools use `30` and `90` days; the ground-truth tools mirror the application's `7`, `28`, and `90` day windows, with `365` also available for the Outcomes ledger. Tool access depends on the project and permissions from your connection:
* OAuth connections use the project you selected during setup and your DevTune role
* API key connections use the project and permissions assigned to the key
`devtune_get_404_demand` uses the existing `traffic.read` scope for API keys and OAuth connections. The other ground-truth tools require an API key with the corresponding `pages.read`, `audit.read`, `outcomes.read`, or `referrals.read` scope and are intentionally excluded from existing OAuth grants until OAuth supports explicit per-grant scope consent. Managed-agent read tools require `agents.read`, while `devtune_run_agent` requires `agents.run`. Existing API keys do not receive new scopes automatically.
Write-capable tools, including `devtune_generate_action_brief`, require permission to manage actions for the selected project.
`devtune_get_content_gaps` maps to `GET /api/v2/projects/{projectId}/content-gaps/list`. It exposes topic and prompt-cluster signals from the Actions system, including `signalStrength`, component metrics, and bounded evidence. Workflow state, briefs, interventions, and `opportunityScore` stay on the Actions tools.
## Tool Inputs
| Tool | Inputs |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `devtune_get_visibility_summary` | `windowDays` (`30`, `90`), optional `platform`, optional `topicId` |
| `devtune_get_competitive_position` | `windowDays` (`30`, `90`), optional `platform`, optional `topicId`, optional `grouping` (`daily`, `weekly`, `monthly`) |
| `devtune_get_citation_analysis` | `windowDays` (`30`, `90`), optional `cursor`, optional `pageSize`, optional `search` |
| `devtune_get_top_citation_pages` | `windowDays` (`30`, `90`), optional `cursor`, optional `pageSize`, optional `search` |
| `devtune_get_top_citation_domains` | `windowDays` (`30`, `90`), optional `cursor`, optional `pageSize`, optional `search` |
| `devtune_get_citation_stats` | `windowDays` (`30`, `90`) |
| `devtune_get_actions` | optional `status`, optional `surface`, optional `priority`, optional `channel`, optional `detailLevel` (`summary`, `context`), optional `page`, optional `pageSize` |
| `devtune_get_action_brief` | `actionId` |
| `devtune_generate_action_brief` | `actionId`, optional `briefStyle` |
| `devtune_get_traffic_summary` | `windowDays` (`30`, `90`), optional `domain` |
| `devtune_get_404_demand` | none |
| `devtune_get_adoption_metrics` | `windowDays` (`30`, `90`), optional `metric` (`github_stars`, `weekly_downloads`) |
| `devtune_get_content_gaps` | `windowDays` (`30`, `90`), optional `cursor`, optional `pageSize` |
| `devtune_get_page_metrics` | `windowDays` (`7`, `28`, `90`), optional `cursor`, `pageSize`, `category`, `sortKey`, `sortDirection` |
| `devtune_get_page_guard_rails` | optional `offset`, optional `pageSize` |
| `devtune_get_audit_summary` | `windowDays` (`7`, `28`, `90`) |
| `devtune_get_audit_findings` | optional `includeDismissed`, optional `offset`, optional `pageSize` |
| `devtune_get_google_eligibility` | optional `windowDays` (`7`, `28`, `90`), optional `evidenceLimit` (`1`-`25`, defaults to `10`); unavailable projects return `Resource not found` |
| `devtune_get_outcomes_ledger` | `windowDays` (`7`, `28`, `90`, `365`), optional `cursor`, `pageSize`, `status` |
| `devtune_get_ai_referrals` | `windowDays` (`7`, `28`, `90`), optional `cursor`, optional `pageSize` |
| `devtune_list_agents` | none |
| `devtune_list_agent_runs` | optional `agentKey`, optional `cursor`, optional `pageSize` |
| `devtune_get_agent_run` | `runId` |
| `devtune_run_agent` | `agentKey`, `requestIdempotencyKey`, optional `instructions`, optional `modelId` |
For `devtune_get_actions`, the most useful filters are:
* `detailLevel`: `summary` or `context`; `summary` is default
* `surface`: `recommendation` or `backlog`
* `status`: `active`, `backlog`, `in_progress`, `blocked`, `done`, `canceled`
* aliases: `open`, `completed`, and `dismissed` map to `backlog`, `done`, and `canceled`
* `priority` and `channel` for narrower work queues
Use `detailLevel: "context"` when the agent needs to understand why an action matters before deciding what to do. Context responses are capped to keep tools fast and predictable: up to 3 evidence blocks and 5 citation/source references per action, plus scores, metrics, brief readiness, and follow-up links. Guard-rail evidence includes `googleEligibility` only when the caller is entitled and the evidence has a fresh observation from a live exact-domain GSC source. It includes `canonical`, `crawlable`, `indexed`, and `structuredData` states (`pass`, `fail`, or `unmeasured`), together with `observedAt` and Google's `coverageState`.
For visibility, citation, content-gap, traffic-summary, adoption, and intelligence tools, `windowDays` accepts `30` or `90` and defaults to `30`. Ground-truth tools accept the windows shown above and default to `28`. Citation top-list tools and content gaps use cursor pagination and return `nextCursor` when another page is available. Citation top-list tools support simple prefix search on URL and domain. `devtune_get_citation_stats` returns aggregate totals only and does not accept pagination or search inputs. Unsupported arbitrary ranges and undocumented filters are rejected instead of being handled downstream.
## Which Tool Should I Use?
| Goal | Tool |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| See the account/project health snapshot | `devtune_get_visibility_summary` |
| Diagnose citation/source movement | `devtune_get_top_citation_pages`, `devtune_get_top_citation_domains`, or `devtune_get_citation_stats` |
| Compare primary brand vs competitors | `devtune_get_competitive_position` |
| Find recommended work | `devtune_get_actions` |
| Understand why a recommendation matters | `devtune_get_actions` with `detailLevel: "context"` |
| Execute a recommendation | `devtune_get_action_brief` or `devtune_generate_action_brief` |
| Diagnose page-level ground truth | `devtune_get_page_metrics`, `devtune_get_page_guard_rails` |
| Review Audit findings and trends | `devtune_get_audit_summary`, `devtune_get_audit_findings` |
| Review Google eligibility | `devtune_get_google_eligibility` |
| Connect work to measured outcomes | `devtune_get_outcomes_ledger` |
| Inspect AI-referral demand | `devtune_get_ai_referrals` |
| Inspect missing-page demand | `devtune_get_404_demand` |
| Review agent availability and runs | `devtune_list_agents`, `devtune_list_agent_runs`, `devtune_get_agent_run` |
| Trigger an idempotent agent run | `devtune_run_agent` |
### Triggering a Managed-Agent Run
`devtune_run_agent` requires the explicit `agents.run` API-key scope and a caller-generated UUID in `requestIdempotencyKey`. Retrying with the same key reuses the existing run. The tool delegates to the same gated dispatch path as the application, including the ground-truth feature flag, model-catalog validation, autonomy rules, and credit reservation and settlement. It creates no external draft-write capability; completed draft artifacts are read with `devtune_get_agent_run` and approval remains in the application.
### Generating Action Briefs
`devtune_generate_action_brief` is the MCP write operation for the Actions workspace. It takes the following inputs:
| Parameter | Type | Description |
| ------------ | ------ | ----------------------------------------------------------------------------------------------- |
| `actionId` | string | UUID of the action to generate a brief for |
| `briefStyle` | string | Optional style override. Use `best_fit` or an allowed content format such as `technical_guide`. |
When project content preferences are enabled, `briefStyle` must respect the project's allowed and blocked formats. Requests for blocked formats are rejected instead of silently generating the blocked style.
The tool is idempotent for a ready or already-running brief:
* If the brief is ready, it returns `status: "ready"`
* If generation is already running, it returns `status: "generating"`
* If generation can start, it queues background work and returns `status: "queued"`
The response includes `success`, `message`, `actionId`, and, when queued, an `eventId`. Use `devtune_get_action_brief` afterward to poll for readiness and retrieve the generated markdown.
## Example Prompts
Once connected, you can ask your AI agent questions like:
* "What is my current share of voice across AI platforms?"
* "Show me the competitive position trend for the last 30 days"
* "Show my top citation pages and domains for the last 90 days"
* "Summarize my aggregate citation stats for the last 30 days"
* "List active recommendations for this project"
* "Load the stored brief for action 6f1e2d3c-1a2b-4c5d-8e9f-0123456789ab and summarize the execution plan"
* "Generate the action brief for action 6f1e2d3c-1a2b-4c5d-8e9f-0123456789ab"
* "Show backlog items that are blocked or in progress"
* "Which content-gap signals are strongest this month, and what evidence supports them?"
* "Show page-level blind spots and guard rails for the last 28 days"
* "Summarize open Audit findings and measured Outcomes for this project"
* "List available agents and their recent runs"
* "Run the Technical Auditor with idempotency key 6f1e2d3c-1a2b-4c5d-8e9f-0123456789ab"
* "How much traffic am I getting from AI chatbots?"
## Related Documentation
* [**Authentication**](/api-reference/authentication) — API key and MCP OAuth authentication
* [**Rate Limits**](/api-reference/rate-limits) — Request limits by plan tier
* [**API Overview**](/api-reference/overview) — Full list of REST API endpoints
# DevTune REST API Reference
Source: https://docs.devtune.ai/api-reference/overview
Integrate DevTune visibility metrics, citations, adoption data, and webhooks into CI/CD pipelines, BI tools, and dashboards with the public REST API.
DevTune provides a public REST API for integrating your AI search visibility data into CI/CD pipelines, BI tools, custom dashboards, and automated workflows. Most endpoints are read-focused analytics endpoints. API keys also power webhook management and non-interactive MCP clients, while MCP clients that support OAuth can use browser sign-in and project selection instead.
## What You Can Do
With the DevTune API you can:
* Pull visibility metrics (share of voice, presence rate, brand mentions) into your reporting tools
* Monitor competitive positioning trends programmatically
* Feed citation data into your own analytics pipelines
* Track adoption metrics (npm downloads, GitHub stars) alongside search visibility
* Pull the current actions workspace, including active recommendations and adopted backlog work
* Trigger command-center brief generation for a specific action
* Build custom alerting on top of DevTune data
* Connect AI coding agents (Codex, Claude, Cursor) via the MCP server for in-IDE access
## Requirements
* A **Plus plan or higher** with API access enabled
* An API key scoped to a specific project
## Available Endpoints
| Endpoint | Description |
| --------------------------------------------------------------- | --------------------------------- |
| `GET /projects/{projectId}/pages/metrics` | List unified page metrics |
| `GET /projects/{projectId}/pages/guard-rails` | List page guard-rail findings |
| `GET /projects/{projectId}/audit/summary` | Get Audit summary |
| `GET /projects/{projectId}/audit/findings` | List Audit findings |
| `GET /projects/{projectId}/audit/eligibility` | Get Google eligibility evidence |
| `GET /projects/{projectId}/outcomes/ledger` | List measured outcomes |
| `GET /projects/{projectId}/traffic/referrals` | List AI referrals |
| `GET /projects/{projectId}/traffic/404-demand` | Get 404 Demand |
| `GET /projects/{projectId}/traffic/direct-lift` | Get AI-correlated Direct lift |
| `GET /projects/{projectId}/agents` | List managed agents |
| `GET /projects/{projectId}/agents/runs` | List managed-agent runs |
| `GET /projects/{projectId}/agents/runs/{runId}` | Get a managed-agent run |
| `POST /projects/{projectId}/agents/{agentKey}/runs` | Trigger a managed-agent run |
| `GET /projects/{projectId}/visibility/summary` | Get visibility summary metrics |
| `GET /projects/{projectId}/citations/stats` | Get aggregate citation statistics |
| `GET /projects/{projectId}/citations/top-domains` | Get top citation domains |
| `GET /projects/{projectId}/citations/top-pages` | Get top citation pages |
| `GET /projects/{projectId}/visibility/diff` | Get visibility diff |
| `GET /projects/{projectId}/content-gaps/list` | List content gaps |
| `GET /projects/{projectId}/competitive/position` | Get competitive positioning data |
| `GET /projects/{projectId}/adoption/metrics` | Get adoption metrics |
| `GET /projects/{projectId}/actions/list` | List actions |
| `GET /projects/{projectId}/actions/{actionId}/brief` | Get action brief |
| `POST /projects/{projectId}/actions/{actionId}/brief` | Generate action brief |
| `GET /projects/{projectId}/traffic/summary` | Get traffic summary |
| `GET /projects/{projectId}/traffic/platforms` | Get traffic by platform |
| `GET /projects/{projectId}/intelligence/anomalies` | Detect intelligence anomalies |
| `GET /projects/{projectId}/intelligence/what-works` | Get what-works recommendations |
| `GET /projects/{projectId}/webhooks` | List webhook subscriptions |
| `POST /projects/{projectId}/webhooks` | Create webhook subscription |
| `DELETE /projects/{projectId}/webhooks/{webhookId}` | Delete webhook subscription |
| `POST /projects/{projectId}/webhooks/{webhookId}/rotate-secret` | Rotate webhook signing secret |
> **Tip:** Full request/response documentation for each endpoint is available in the **Endpoints** section of the API Reference sidebar, auto-generated from the OpenAPI specification.
The [webhooks guide](/api-reference/webhooks) documents real-time event notifications, and the [MCP server guide](/api-reference/mcp-server) covers agent access. The machine-readable specification is available at `GET /api/v2/openapi.json`.
### Actions Endpoint Notes
The actions endpoint reflects the current workspace model:
* `surface` lets you filter between `recommendation` and `backlog`
* `detailLevel=summary` is default; `detailLevel=context` adds bounded why-now context, scores, metrics, top evidence, brief readiness, and follow-up links
* `status` uses public workspace states: `active`, `backlog`, `in_progress`, `blocked`, `done`, `canceled`
* `active` applies to recommendations; the rest apply to adopted backlog work
* The aliases `open`, `completed`, and `dismissed` are also accepted for compatibility and map to `backlog`, `done`, and `canceled`
### Citations vs Mentions
Public citation endpoints are named `/citations/*` because they describe cited sources: pages, domains, classifications, positions, and evidence references. "Mentions" has a separate DevTune meaning: brand or product mentions inside AI answer text.
Public windowed REST endpoints use `windowDays` with endpoint-specific fixed rolling windows.
Citation top-list and content-gap list endpoints use cursor pagination. Pass `pageSize` up to `100`; when a response includes `nextCursor`, send it as `cursor` to retrieve the next page. Citation top-list endpoints support simple prefix matching on URL and/or canonical domain. The public API does not support contains search, arbitrary sort columns, classification filters, broad content/source filters, or citation compare requests.
### Response Caching
Read-focused analytics endpoints may return short-lived cached responses to reduce repeated polling overhead. Clients should respect the `Cache-Control` response header. If an integration needs to force a fresh read, send `Cache-Control: no-cache` with the request.
### Fixed Windows
* Visibility summaries, competitive position, citation stats, top pages, top domains, content gaps, traffic summary, traffic platforms, adoption metrics, what-works recommendations, visibility diff, and intelligence anomalies accept `windowDays=30` or `90` and default to `30`.
* Page metrics, Audit summary, Audit eligibility, AI referrals, and AI-correlated Direct lift accept `windowDays=7`, `28`, or `90` and default to `28`.
* Outcomes Ledger accepts `windowDays=7`, `28`, `90`, or `365` and defaults to `28`.
* Responses expose the resolved selection as `window` or `windowDays`, depending on the endpoint. Use the response schema for that endpoint instead of assuming one shared shape.
### Action Brief Write Operation
Use `POST /api/v2/projects/{projectId}/actions/{actionId}/brief` to generate or reuse an execution-ready action brief.
This endpoint requires the `actions.write` API key scope. It does not create duplicate work for briefs that are already ready or generating. The response returns the current state:
* `ready`: a usable brief already exists
* `generating`: background generation is already running
* `queued`: DevTune queued generation and returned an `eventId`
After a `queued` or `generating` response, use `GET /api/v2/projects/{projectId}/actions/{actionId}/brief` to poll for `status: "ready"` and retrieve `briefMarkdown`.
You can optionally send `briefStyle` in the request body to ask for `best_fit` or a specific allowed content format. If project content preferences are enabled, the requested style must be allowed for the project.
## Getting Started
1. **[Create an API key](/api-reference/authentication)** from API Keys in the account sidebar
2. **Make your first request** using the key in the `Authorization` header
3. **Explore the endpoints** to find the data you need
For OAuth-based agent access, connect through the [MCP server](/api-reference/mcp-server) instead of creating an API key.
## Quick Example
```bash theme={null}
curl -H "Authorization: Bearer dtk_live_your_key_here" \
"https://devtune.ai/api/v2/projects/YOUR_PROJECT_ID/visibility/summary"
```
```json theme={null}
{
"data": {
"totalExecutions": 142,
"shareOfVoice": 23.5,
"citationPresence": 68.2,
"brandAwareness": 45.1,
"avgPrimaryPosition": 2.3,
"primaryCitations": 97,
"competitorCitations": 215
},
"meta": {
"timestamp": "2026-02-08T12:00:00.000Z",
"projectId": "your-project-id"
}
}
```
### Generate an Action Brief
```bash theme={null}
curl -X POST \
-H "Authorization: Bearer dtk_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{"briefStyle":"best_fit"}' \
"https://devtune.ai/api/v2/projects/YOUR_PROJECT_ID/actions/ACTION_ID/brief"
```
```json theme={null}
{
"data": {
"actionId": "ACTION_ID",
"eventId": "evt_123",
"message": "Brief generation started in the background.",
"status": "queued",
"success": true
},
"meta": {
"timestamp": "2026-02-08T12:00:00.000Z",
"projectId": "your-project-id"
}
}
```
## Related Documentation
* **[Authentication](/api-reference/authentication)** - API key creation and usage
* **[Rate Limits](/api-reference/rate-limits)** - Request limits by plan tier
* **[Error Handling](/api-reference/errors)** - Error codes and troubleshooting
# API Rate Limits
Source: https://docs.devtune.ai/api-reference/rate-limits
DevTune REST API per-key rate limits by Plus, Pro, and Enterprise plan tiers, including request quotas, throttling behavior, and 429 response handling.
The DevTune API enforces per-key rate limits to ensure fair usage. Limits are based on your subscription plan tier.
## Limits by Plan
| Plan | Requests per Minute |
| ---------- | ------------------- |
| Plus | 100 |
| Pro | 500 |
| Enterprise | 1,000 |
Rate limits are applied per API key, not per account. If you have multiple keys, each has its own independent limit.
## Rate Limit Headers
Every API response includes headers that tell you your current rate limit status:
| Header | Description |
| ----------------------- | ----------------------------------------------- |
| `X-RateLimit-Limit` | Maximum requests allowed per window |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset` | Unix timestamp (seconds) when the window resets |
### Example Response Headers
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1707400800
```
## When You Exceed the Limit
If you exceed your rate limit, the API returns a `429 Too Many Requests` response:
```json theme={null}
{
"error": "rate_limit_exceeded",
"message": "Rate limit exceeded. Please try again later.",
"status": 429
}
```
The response includes rate limit headers so you know when to retry.
## Best Practices
* **Check the headers** before making rapid requests. Use `X-RateLimit-Remaining` to pace your calls.
* **Use exponential backoff** when you receive a 429. Wait until the `X-RateLimit-Reset` timestamp before retrying.
* **Cache responses** where possible. Most DevTune data updates once per day (after scheduled tracking runs), so caching for several minutes is usually appropriate.
* **Batch your reads** rather than polling frequently. Pull data once and process it locally.
## Related Documentation
* **[Authentication](/api-reference/authentication)** - API key setup
* **[Error Handling](/api-reference/errors)** - All error responses
# Rotate webhook signing secret
Source: https://docs.devtune.ai/api-reference/rotate-webhook-signing-secret
/openapi.json post /projects/{projectId}/webhooks/{webhookId}/rotate-secret
Generates a new HMAC-SHA256 signing secret for the webhook subscription. The old secret is invalidated immediately. The new secret is only returned once in this response. Requires the webhooks.write scope.
# Trigger a managed-agent run
Source: https://docs.devtune.ai/api-reference/trigger-a-managed-agent-run
/openapi.json post /projects/{projectId}/agents/{agentKey}/runs
Queues or reuses a manual run through the existing flag, credit metering, model-catalog, idempotency, and autonomy controls. This endpoint has a stricter rate limit than read endpoints.
# Webhooks
Source: https://docs.devtune.ai/api-reference/webhooks
Receive real-time HTTP notifications when DevTune visibility metrics change or AI Search runs complete, with payload examples and signature verification.
Webhooks let you receive real-time HTTP notifications when events occur in your project. DevTune will POST a JSON payload to your configured URL whenever a subscribed event fires.
## Event Types
| Event | Description |
| ------------------------------- | ------------------------------------------------------------------------ |
| `search-tracking.completed` | A search tracking run has finished processing |
| `visibility.changed` | Visibility metrics have been calculated after a search tracking run |
| `action.created` | An action has been created by DevTune, a user, or the API |
| `action.updated` | A customer-visible action field changed |
| `action.recommendation.created` | A new visible recommendation appears in the Actions workspace |
| `action.recommendation.updated` | A visible recommendation changes materially and should be reviewed again |
`action.*` events track the action entity lifecycle. `action.recommendation.*` events track the recommendation surface. Recommendation update events are intentionally quiet: they do not fire for recommendation reorder, accepted/backlog movement, small citation drift, evidence reorder, wording-only changes, or brief absence alone.
## Managing Webhooks via the Dashboard
You can create and manage webhooks directly from your account settings in the DevTune dashboard.
1. Navigate to your team account
2. Open **Webhooks** in the account sidebar
3. Click **Create Webhook**
4. Fill in the form:
* **Endpoint URL** — The HTTPS URL that will receive webhook POST requests
* **Project** — Select which project's events should trigger the webhook
* **Events** — Check one or more event types to subscribe to
5. Click **Create Webhook**
6. Copy the **signing secret** shown in the dialog — this is the only time it will be displayed
7. If you ever need a new secret, click the **rotate** icon next to the webhook — this generates a new secret and invalidates the old one immediately
You can view all your webhooks in the table, and delete any active webhook using the trash icon. Use the "Hide inactive" toggle to filter out previously deleted webhooks.
> **Note:** The Webhooks page requires the **Plus plan** or above (API Access entitlement). You must also have the **settings.manage** permission on the team account.
## Managing Webhooks via the API
Scoped API keys must include:
* `webhooks.read` to list webhook subscriptions
* `webhooks.write` to create, delete, or rotate webhook secrets
### Create a Webhook
```
POST /api/v2/projects/{projectId}/webhooks
```
#### Request Body
```json theme={null}
{
"url": "https://your-app.com/webhooks/devtune",
"events": ["action.created", "action.recommendation.created"]
}
```
#### Response (201)
```json theme={null}
{
"data": {
"id": "uuid",
"url": "https://your-app.com/webhooks/devtune",
"events": ["action.created", "action.recommendation.created"],
"isActive": true,
"secret": "a1b2c3d4...hex-string",
"createdAt": "2026-02-08T12:00:00.000Z"
},
"meta": { "timestamp": "...", "projectId": "..." }
}
```
The `secret` is only returned when creating the webhook. Store it securely for signature verification.
### List Webhooks
```
GET /api/v2/projects/{projectId}/webhooks
```
Returns all active webhook subscriptions for the project.
#### Response (200)
```json theme={null}
{
"data": {
"webhooks": [
{
"id": "uuid",
"url": "https://your-app.com/webhooks/devtune",
"events": ["action.created", "action.recommendation.created"],
"isActive": true,
"createdAt": "2026-02-08T12:00:00.000Z"
}
]
},
"meta": { "timestamp": "...", "projectId": "..." }
}
```
### Delete a Webhook
```
DELETE /api/v2/projects/{projectId}/webhooks/{webhookId}
```
Deactivates the webhook subscription.
#### Response (200)
```json theme={null}
{
"deleted": true
}
```
Returns 404 if the webhook ID does not exist or belongs to a different project.
### Rotate Webhook Secret
```
POST /api/v2/projects/{projectId}/webhooks/{webhookId}/rotate-secret
```
Generates a new HMAC-SHA256 signing secret for the webhook. The old secret is invalidated immediately — any deliveries signed with the old secret will no longer verify.
No request body is required.
#### Response (200)
```json theme={null}
{
"data": {
"secret": "new-a1b2c3d4...hex-string"
},
"meta": { "timestamp": "...", "projectId": "..." }
}
```
Returns 404 if the webhook does not exist, belongs to a different project, or is inactive.
## Webhook Payload Format
When an event fires, DevTune sends a POST request with this body:
```json theme={null}
{
"event": "search-tracking.completed",
"projectId": "your-project-id",
"accountId": "your-account-id",
"timestamp": "2026-02-08T12:00:00.000Z",
"data": {
"runId": "run-uuid",
"finalStatus": "completed"
}
}
```
### `visibility.changed` payload
```json theme={null}
{
"event": "visibility.changed",
"projectId": "your-project-id",
"accountId": "your-account-id",
"timestamp": "2026-02-10T06:00:00.000Z",
"data": {
"runId": "run-uuid",
"capturedOn": "2026-02-10",
"metrics": {
"visibilityScore": 0.75,
"citationCount": 12,
"brandMentionCount": 5,
"sampleCount": 20
},
"previousMetrics": {
"visibilityScore": 0.6,
"citationCount": 8,
"brandMentionCount": 3,
"sampleCount": 18,
"capturedOn": "2026-02-09"
}
}
}
```
`previousMetrics` is `null` when there is no prior data (e.g., the first run for a project).
### `action.created` payload
```json theme={null}
{
"event": "action.created",
"projectId": "your-project-id",
"accountId": "your-account-id",
"timestamp": "2026-05-02T12:00:00.000Z",
"data": {
"event": "action.created",
"actionId": "action-uuid",
"origin": "user",
"actor": { "type": "user", "userId": "user-uuid" },
"changedFields": [],
"action": {
"id": "action-uuid",
"title": "Update the pricing page integration section",
"description": "Competitors are being cited for integration details that your page does not cover.",
"status": "backlog",
"surface": "backlog",
"priority": "high",
"channels": ["content", "product"],
"target": { "label": "/pricing", "type": "page", "payload": {} },
"expectedImpact": "Improve coverage for high-intent pricing prompts.",
"whatChanged": "Competitor pages gained citations for pricing integration questions.",
"updatedAt": "2026-05-02T11:58:10.000Z"
},
"links": {
"apiActionContext": "/api/v2/projects/your-project-id/actions/list?detailLevel=context",
"mcpActionContext": {
"tool": "devtune_get_actions",
"args": { "detailLevel": "context" }
},
"mcpActionBrief": {
"tool": "devtune_get_action_brief",
"args": { "actionId": "action-uuid" }
}
}
}
}
```
### `action.updated` payload
```json theme={null}
{
"event": "action.updated",
"projectId": "your-project-id",
"accountId": "your-account-id",
"timestamp": "2026-05-02T12:00:00.000Z",
"data": {
"event": "action.updated",
"actionId": "action-uuid",
"origin": "user",
"actor": { "type": "user", "userId": "user-uuid" },
"changedFields": ["status", "assigned_to"],
"action": {
"id": "action-uuid",
"title": "Update the pricing page integration section",
"status": "in_progress",
"surface": "backlog",
"priority": "high"
},
"links": {
"apiActionContext": "/api/v2/projects/your-project-id/actions/list?detailLevel=context",
"mcpActionContext": {
"tool": "devtune_get_actions",
"args": { "detailLevel": "context" }
}
}
}
}
```
### `action.recommendation.created` payload
```json theme={null}
{
"event": "action.recommendation.created",
"projectId": "your-project-id",
"accountId": "your-account-id",
"timestamp": "2026-05-02T12:00:00.000Z",
"data": {
"event": "action.recommendation.created",
"actionId": "action-uuid",
"origin": "system",
"actor": { "type": "system" },
"changedFields": [],
"action": {
"id": "action-uuid",
"title": "Update the pricing page integration section",
"status": "active",
"surface": "recommendations",
"priority": "high",
"channels": ["content", "product"],
"target": { "label": "/pricing", "type": "page", "payload": {} },
"expectedImpact": "Improve coverage for high-intent pricing prompts.",
"whatChanged": "Competitor pages gained citations for pricing integration questions.",
"updatedAt": "2026-05-02T11:58:10.000Z"
},
"recommendationContext": {
"bucket": "do_now",
"scores": { "opportunity": 0.84, "effort": 0.35 },
"whyNow": "Recent prompt evidence shows the gap is active.",
"topEvidence": [
{
"id": "evidence-block-uuid",
"title": "Prompt landscape on pricing",
"summary": "12 tracked prompts generated 88 citations in the last 30 days.",
"type": "citation_shift"
}
],
"briefReadiness": {
"hasBrief": false,
"status": null,
"generatedAt": null,
"updatedAt": null
},
"changeReasons": []
},
"links": {
"apiActionContext": "/api/v2/projects/your-project-id/actions/list?detailLevel=context",
"mcpActionContext": {
"tool": "devtune_get_actions",
"args": { "detailLevel": "context" }
},
"mcpActionBrief": {
"tool": "devtune_get_action_brief",
"args": { "actionId": "action-uuid" }
}
},
"review": {
"classification": "brief_stale_only",
"fingerprintKey": "stable-review-fingerprint"
}
}
}
```
### `action.recommendation.updated` payload
`action.recommendation.updated` uses the same payload shape as `action.recommendation.created`, with `recommendationContext.changeReasons` explaining why review is recommended.
```json theme={null}
{
"event": "action.recommendation.updated",
"projectId": "your-project-id",
"accountId": "your-account-id",
"timestamp": "2026-05-02T12:00:00.000Z",
"data": {
"event": "action.recommendation.updated",
"actionId": "action-uuid",
"origin": "system",
"actor": { "type": "system" },
"changedFields": ["target_label", "priority"],
"action": {
"id": "action-uuid",
"title": "Update the pricing page integration section",
"status": "active",
"surface": "recommendations",
"priority": "high"
},
"recommendationContext": {
"bucket": "do_now",
"changeReasons": ["concrete_target_changed", "prompt_set_changed"]
},
"links": {
"apiActionContext": "/api/v2/projects/your-project-id/actions/list?detailLevel=context",
"mcpActionContext": {
"tool": "devtune_get_actions",
"args": { "detailLevel": "context" }
}
}
}
}
```
To fetch full context after either event, use:
* `GET /api/v2/projects/{projectId}/actions/list?detailLevel=context`
* `GET /api/v2/projects/{projectId}/actions/{actionId}/brief`
* MCP `devtune_get_actions` with `detailLevel: "context"`
* MCP `devtune_get_action_brief`
### Headers
| Header | Description |
| --------------------- | -------------------------------------------------- |
| `Content-Type` | `application/json` |
| `X-DevTune-Signature` | HMAC-SHA256 hex digest of the request body |
| `X-DevTune-Event` | The event type (e.g., `search-tracking.completed`) |
| `User-Agent` | `DevTune-Webhook/2.0` |
## Verifying Signatures
Every webhook delivery includes an `X-DevTune-Signature` header containing an HMAC-SHA256 hex digest computed with your webhook secret.
### Node.js Example
```javascript theme={null}
const crypto = require('crypto');
function verifyWebhook(rawBody, signature, secret) {
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest();
const received = Buffer.from(signature, 'hex');
if (expected.length !== received.length) return false;
return crypto.timingSafeEqual(received, expected);
}
```
> **Important:** Use the raw request body (before JSON parsing) for signature verification. In Express, use `express.raw({ type: 'application/json' })` on your webhook route to get the raw buffer.
### Python Example
```python theme={null}
import hmac
import hashlib
def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(
secret.encode(), body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected)
```
## Retry Policy
Failed deliveries (non-2xx responses or timeouts) are retried up to 3 times with exponential backoff. Each attempt is logged in the delivery log visible in the DevTune dashboard.
## Use Cases
* **Slack notifications** when a tracking run finishes
* **CI/CD triggers** to re-run checks when visibility changes
* **Data pipelines** that sync DevTune data to your warehouse on each update
* **GTM automation** that feeds generated actions into triage systems or agentic workflows
## Related Endpoints
* **[Authentication](/api-reference/authentication)** - API key creation and usage
* **[Error Handling](/api-reference/errors)** - Error codes and troubleshooting
# Audit
Source: https://docs.devtune.ai/audit/overview
Use domain readiness, page evidence, diagnoses, and findings to decide what needs attention.
**Audit** brings technical readiness and page-level search evidence into one project view. Use it to find access problems, inspect why a page needs attention, and turn supported findings into work in Actions.
## Open Audit
1. Open a project
2. Select **Audit** in the project sidebar
3. Choose **Domains** or **Pages**
Audit does not turn missing sources into zeroes. When a crawl, Search Console, AI-answer, or traffic source does not cover a page, the affected value appears as unavailable or unmeasured.
## Domains
The **Domains** tab focuses on technical readiness for owned domains.
Select a domain to review:
* **Overall readiness** out of 100
* **AEO readiness**, **Agent readiness**, and **SEO health** pillars
* Host checks for crawler access, sitemap coverage, indexability, and orphan pages
* **Readiness over time** across completed audits
* Open findings grouped by severity
External properties can appear for visibility context, but host-level checks do not apply to them. A subdomain may inherit host checks from its owned parent domain; Audit labels that relationship instead of presenting a separate measurement.
### Work with findings
Expand a finding to read **What to change**, verification guidance, affected pages, and attached evidence. If your account role can manage the project, you can:
* Select **Create action** to review a prefilled title and send the finding to Actions
* Select **Dismiss finding** when it should no longer appear as open
* Restore a dismissed finding later
Creating an action does not change the site. It creates reviewable work with the finding evidence attached.
## Pages
The **Pages** tab combines classic search, AI-answer, crawl, and traffic evidence for individual pages. Use the **7 days**, **28 days**, and **90 days** controls to change the reporting window.
The summary band shows:
* **Classic search clicks** from Google Search Console
* **AI citations (probes)** from tracked AI answers
* **Pages ready**, the share of assessed pages with a citability score of at least 80
* **Locked pages**, which are excluded from automated suggestions and change actions
Below the summary, the daily trend keeps classic clicks, AI citations, and answer fetches on separate scales. Coverage notices state when Search Console or crawl measurement is incomplete.
### Needs attention
**Needs attention** groups pages by the strongest available diagnosis, then orders the highest-opportunity pages first within each group. Diagnoses include:
* **Lost citations & presence**
* **Cited, at risk**
* **Ranks on Google, not cited**
* **Fetched, not cited**
* **Locked**
* **No traction**
* **Healthy**
Healthy and lower-priority pages remain available in **All pages** even when they are not promoted into **Needs attention**.
### Inspect a page
Select a row in **All pages** to open the page inspector. It shows:
* Clicks, impressions, average position, AI citations, citability, and answer fetches
* **Direct traffic** status and supporting comparison when enough sources are measured
* **Google eligibility** signals for indexing, canonical selection, crawlability, and structured data
* Daily citation history
* The latest crawled content preview and content-change dates
* A link to queued work in Actions, when present
DevTune does not monitor Google manual actions or security issues. Check those reports directly in Search Console.
If you can manage the project, the inspector also lets you lock or unlock a page. A lock protects the page from automated suggestions and change actions; it does not remove the page's evidence from Audit.
## Next steps
* [Interpret Direct traffic](/ai-traffic/direct-traffic)
* [Review measured outcomes](/insights-actions/outcomes)
* [Work from Actions](/insights-actions/actions-hub)
# Community Discourse Overview
Source: https://docs.devtune.ai/community-discourse/overview
Track developer-community threads on Reddit, Hacker News, GitHub, Dev.to, and Stack Overflow, with citation overlaps and brand presence in one project view.
Community Discourse helps you understand how your product, competitors, and tracked topics show up in developer communities. It turns raw threads and replies into a project-level view of where the conversation is happening and which discussions overlap with your visibility opportunities.
## What Community Discourse Tracks
Community Discourse focuses on relevant conversations across supported sources:
* Dev.to
* Stack Overflow / Stack Exchange
* Hacker News
* GitHub
* Reddit threads
* Reddit comments on plans that include comment expansion
The system uses your configured brands and tracked URLs to find threads worth paying attention to, then summarizes how those threads connect back to your product and AI Search footprint.
## What You See on the Page
The page is organized around a shared source/date filter bar and a set of summary views:
### KPI cards
At the top of the page, DevTune summarizes the current slice with metrics such as:
* **Threads** - Relevant threads captured in the selected range
* **Relevant replies** - Replies/comments that materially contribute to the discussion
* **Source overlaps** - Threads that exactly overlap with tracked or AI-cited URLs
* **Clusters** - Threads where your primary brand and competitors appear together
### Top Communities
Shows which communities are producing the most relevant discussion volume for the selected filters.
### Brand Share
Shows how often your primary brand and tracked competitors appear across the captured community conversations.
### Intent Mix
Breaks the discussion into practical buckets such as recommendation, comparison, problem, tutorial, and other conversation types.
### Community Threads
The main thread table supports two views:
* **Latest** - Recently indexed discussions
* **Top** - Highest-scoring discussions
You can also toggle **Clusters only** to focus on threads where your brand and competitors are showing up together.
### Source-Linked Threads
This section isolates threads that contain exact overlaps with your tracked URLs or URLs already being cited in AI Search.
### Citations from Community Threads
This table shows the top community-thread citations for the current filter state. It follows the same page filters and highlights the strongest overlaps rather than showing a long paginated tail.
## Filters
Community Discourse uses shared page filters:
* **Source**
* **Date range**
These filters apply consistently across the KPI cards, charts, thread tables, and community citation table.
## Plan Differences
Community Discourse is available on paid plans, but the source mix differs by tier:
* **Starter / Plus** - Dev.to, Stack Overflow, Hacker News, GitHub, and Reddit threads
* **Enterprise** - Everything above, plus Reddit comments
This means lower-tier plans still see the thread layer across all core sources, while Enterprise plans get deeper Reddit discussion coverage.
## How to Use It
Community Discourse is most useful when you treat it as the bridge between raw community conversation and the rest of the DevTune workspace:
1. Use **Top Communities** and **Brand Share** to see where the conversation is strongest
2. Review **Latest** and **Top** threads for concrete discussion examples
3. Check **Source-Linked Threads** to find community conversations that directly overlap with your tracked URLs
4. Use **Actions** to turn the strongest patterns into content, docs, or competitive response work
## Best Practices
* Keep your **Brands** and **tracked URLs** up to date in Project Settings so community matching stays relevant
* Use **Clusters only** when you want to focus on discussions where competitors are actively present
* Pair Community Discourse with **AI Search** and **Owned Content** to see whether relevant discussion is also turning into citations and traffic
## Next Steps
* **[Project Navigation](/projects/project-navigation)** - See where Community Discourse fits in the workspace
* **[Actions Workspace](/insights-actions/actions-hub)** - Turn discussion signals into prioritized work
* **[AI Search Overview](/search-tracking/overview)** - Compare community signals with AI Search visibility
# Cross-Signal Timeline
Source: https://docs.devtune.ai/community-discourse/timeline
Use the Timeline page to align AI Search movement, community activity, content changes, annotations, and outcomes on one shared chronology.
The **Timeline** page is the cross-signal change log for a project. It is designed to answer the question: **what changed, when, and what else was happening at the same time?**
> **DevTune 2.0:** This page documents the legacy GTM What Changed experience. Accounts using the 2.0 project experience are redirected to **Outcomes → Timeline**, which focuses on measured actions, content changes, and outcome evidence. Accounts on the legacy experience retain the cross-signal page described below.
Instead of looking at AI Search, community activity, owned-content changes, and action outcomes in isolation, the Timeline page places them on one shared chronology.
## What the Timeline Page Shows
The page combines filters, summary cards, a shared timeline chart, and event lists.
### Summary cards
At the top of the page, DevTune summarizes the selected window with counts such as:
* **Annotations**
* **Content Changes**
* **Interventions**
* **Post-change Page Citations**
### Downstream Context card
The **Downstream Context** card appears below the timeline and connects your GTM activities to measurable business outcomes. It bridges the gap between upstream work (content changes, community engagement) and downstream results (adoption, AI citations).
The card displays two metrics:
**Adoption Tracking**
Shows the number of tracked domains (GitHub repos, package registries) and the most significant adoption trend in your competitive set. This validates whether your GTM efforts translate into actual package downloads or repository growth.
**Action Outcomes**
* **Correlated Interventions**: Actions you completed where the system detected a measurable citation increase afterward
* **Post-change Page Citations**: Primary AI citations received by pages after DevTune detected a real content change on those pages
### Understanding Interventions
An **intervention** is created automatically when you mark an Action as "Done." It tracks:
* The target URL you were working on (e.g., a docs page)
* Baseline citation metrics before your change
* Content hash at completion time
When your domain is crawled after the change, the system compares new citation counts to the baseline. If citations increased, the intervention is marked as **correlated** — validating that your Action had measurable impact.
### Understanding Post-change Page Citations
A **post-change page citation** is a primary AI citation received by a page after a domain crawl detected a real content change on that same URL. It is scoped to changed pages, not total project citation volume.
This metric is intentionally separate from Actions, backlog items, and outcome markers:
* A project can have post-change page citations even when no Actions have been accepted into the backlog
* A project can have many primary citations overall while showing few or no post-change page citations
* Outcome markers still show completed Actions and detected changes as timeline events
Citation movement can lag content changes. The Timeline counts primary citations to a changed URL for up to 90 days after the crawl-detected change, and plots the citation on the date it was observed.
**Example**: DevTune detects a change to your "Getting Started" page on March 1st. Between March 5-15, that specific page gets cited 12 times across ChatGPT, Claude, and Perplexity. Your post-change page citation count for that window is 12.
This metric answers: *"Are pages that changed recently showing up in AI citations afterward?"*
### Timeline chart
The main chart overlays multiple signal types across the same date range so you can see whether movement in one part of the system lines up with another. Outcome markers appear as visual indicators showing when Actions were completed and when content changes were detected on specific URLs.
### Event lists
Below the chart, DevTune breaks the period into event streams such as:
* Manual annotations
* Owned-content changes
* Community-linked movement
* Outcome / intervention context
### Understanding Outcome Markers vs Completed Actions
**Completed Actions** are work items your team finished (e.g., "Update authentication docs page"). When you mark an Action as Done, the system creates both an **intervention** (which tracks citation metrics for correlation) and an **outcome marker** (a visual indicator on the timeline).
**Outcome markers** are visual timeline indicators showing two distinct event types:
* **Action completed markers** (blue dots) — When Actions targeting specific URLs were marked Done
* **Change detected markers** (amber/green dots) — When domain crawls detected content changes on those URLs
A single Completed Action creates one action-completed marker. However, a URL can accumulate multiple markers over time — your initial action completion, followed by subsequent content changes detected during crawls. This helps you visualize the sequence: *"We completed work on March 1st, the page changed on March 5th, then changed again on March 10th."*
The key distinction: **Completed Actions** are work items in your workflow; **outcome markers** are timeline visualizations showing when events occurred on specific URLs.
## Filters
The Timeline page follows the same shared controls as the AI Search and Community Discourse surfaces:
* **Source**
* **Date range**
These filters narrow both the chart and the underlying event lists.
## Annotations
The Timeline page supports manual annotations so your team can mark launches, docs updates, campaigns, migrations, or other events that may explain downstream changes. This is especially useful when you want to separate deliberate work from ambient market movement.
## How to Use It
The best use of the Timeline page is causal investigation:
1. Choose a date range where you saw a notable gain or drop
2. Review the timeline chart for movement across signals
3. Inspect the event lists around the same period
4. Add annotations for launches or changes that are missing context
5. Use the evidence to decide whether the movement was caused by your work, competitor movement, or broader discussion/activity shifts
## Best Practices
* Use annotations consistently for launches, migrations, major docs updates, and campaign starts
* Review Timeline when a metric changes sharply and the cause is not obvious from a single page
* Pair it with **Actions** and **Owned Content** when you want to connect shipped work to downstream signal movement
## Next Steps
* **[Community Discourse Overview](/community-discourse/overview)** - Review the community side of the signal set
* **[Actions Workspace](/insights-actions/actions-hub)** - Turn timeline signals into suggestions and backlog work
* **[Owned Content](/content-explorer/overview)** - Review the content changes that appear on the timeline
# Technical AEO Audit
Source: https://docs.devtune.ai/content-explorer/aeo-audit
Understand the AEO health report in Owned Content, including crawl coverage, extractability, metadata, sitemap freshness, AI crawler access, llms.txt, and remediation prompts.
The technical AEO audit shows whether AI crawlers and answer engines can discover, fetch, extract, and understand your primary brand domains. It appears in **Owned Content** above Content Explorer as the **AEO health** report.
Use the audit to find technical blockers before you spend time rewriting content. If AI systems cannot crawl a page, extract meaningful text, or discover your canonical URLs, they are less likely to cite or represent that content accurately.
## What It Answers
The audit helps answer:
* Can AI search crawlers access the public site?
* Did DevTune capture enough owned content to assess the domain?
* Are important pages extractable as meaningful text or markdown?
* Do pages expose useful titles and basic metadata?
* Does the sitemap help crawlers discover URLs and freshness signals?
* Is optional `llms.txt` guidance present?
## Where To Find It
1. Open your project
2. Go to **Owned Content**
3. Review the **AEO health** section above Content Explorer
Each audited domain appears as a compact row with its status, score, checked date, and finding count. Expand a domain to inspect the checks that produced the score.
## How It Runs
DevTune runs the audit from two low-cost sources:
| Source | What It Uses |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Owned crawl data** | Active crawled pages already captured for the domain |
| **Live HTTP probes** | Lightweight checks for the homepage, robots rules, sitemap discovery, sitemap freshness, AI crawler access, and `llms.txt` |
Owned crawl checks reuse existing crawl data rather than starting a new paid crawl. Live probes are small HTTP requests against public resources such as `/robots.txt`, `/sitemap.xml`, `/llms.txt`, and the homepage.
Audits refresh after completed domain crawls when the prior result is stale. Eligible primary domains are also scheduled for a monthly refresh.
## Checks
### Crawl Coverage
Checks whether active crawled pages are available for the domain and whether the crawl includes the homepage. If no pages are available yet, run or wait for the owned-content crawl before treating the result as a website remediation task.
### Content Extractability
Looks for pages that extracted as nearly empty or unusually thin. This can indicate JavaScript-only content, bot protection, consent gates, redirects, or templates that do not expose meaningful crawler-readable text.
### Markdown Extraction
Checks whether the crawl returned markdown as the primary content format. Markdown is easier to review and generally indicates that the page structure was captured cleanly.
### Metadata
Checks for missing page titles and descriptions across active crawled pages. Titles and descriptions help crawlers and answer systems identify page purpose and brand context.
### Content Freshness
Uses sitemap `lastmod` coverage as a freshness signal. Accurate `lastmod` values help crawlers decide which pages deserve recrawling. Missing or partial `lastmod` coverage is a warning, not a crawler block.
### AI Crawler Access
Checks robots rules and homepage responses for AI search and retrieval crawlers, including `OAI-SearchBot`, `ChatGPT-User`, `Claude-SearchBot`, and `PerplexityBot`. Training crawler restrictions are reported separately because they may be intentional.
### Sitemap
Checks whether a valid XML sitemap exists at the standard location or is declared in `robots.txt`. The audit validates sitemap-like content instead of treating every successful `/sitemap.xml` response as valid.
### Homepage HTML
Checks whether the homepage returns enough raw HTML text and whether it includes `noindex` directives in robots meta tags or `X-Robots-Tag` headers.
### llms.txt
Checks whether `/llms.txt` exists. This is optional and not a blocker, but it can provide concise guidance and canonical links for AI agents.
## Reading The Report
When you expand a domain, the left side lists checks with their score and status. Selecting a check opens three tabs:
| Tab | What It Shows |
| ---------------- | -------------------------------------------------------------------------------------------------- |
| **Details** | The evidence behind the check, including affected URLs when available |
| **Findings** | Actionable issues and remediation guidance for that check |
| **Agent prompt** | A copyable website-scoped prompt when the finding is suitable for an external implementation agent |
The **Copy full report** button exports the audit evidence for review. The **Copy prompt for all findings** button appears only when there are actionable website fixes that can be safely handed to an implementation agent.
## Multi-Domain Projects
DevTune audits each primary domain separately. For example, your main marketing site and docs site can have separate AEO health rows if both are configured as primary domains for the project.
The top-level status is intentionally conservative: it highlights the weakest domain so a broken docs site or blocked homepage does not get hidden behind a stronger domain.
## Public Brand Pages
Public brand report pages may show a lightweight AEO readiness scorecard. That public scorecard shares broad crawlability signals only. Exact findings, affected URLs, remediation details, and audit history remain inside the signed-in DevTune app.
## Acting On Findings
Use the remediation guidance to separate website fixes from DevTune data freshness:
* **No crawled pages available** means the owned-content crawl has not produced active pages yet. Run or wait for the crawl first.
* **Crawler access blocked** usually points to robots rules, CDN/WAF policy, bot protection, or non-OK responses to AI crawler user agents.
* **Thin or empty extracted pages** usually points to client-only rendering, gated content, redirects, extraction-unfriendly markup, or pages that genuinely need more indexable explanation.
* **Missing sitemap or low `lastmod` coverage** usually points to sitemap generation, canonical host, or `robots.txt` discovery.
* **Missing metadata** usually points to page templates that do not generate unique titles or descriptions.
After making website changes, run a fresh domain crawl or wait for the next crawl and audit refresh. The report should update once DevTune has new crawl data or live probe results.
## Next Steps
* **[Browsing Content](/content-explorer/browsing-content)** - Review the crawled pages behind the audit
* **[Version History](/content-explorer/version-history)** - Confirm content updates were captured after a crawl
* **[AI Demand](/ai-traffic/overview)** - See what AI systems retrieve and the visible referral tail
# Browsing Owned Content
Source: https://docs.devtune.ai/content-explorer/browsing-content
Navigate the Content Explorer sitemap tree, search and filter crawled pages, view rendered content, and inspect per-page AI bot traffic and referrals.
The Owned Content workspace uses Content Explorer as its main interface. It has two panels: a sitemap tree on the left for navigation, and a detail panel on the right that shows the selected page's content, history, and traffic data.
Owned Content also includes an **AEO health** report above the explorer. Use it to review domain-level crawler-readiness checks before drilling into individual crawled pages.
## Accessing Owned Content
1. Select your project from the account home page
2. In the sidebar, open **Owned Content**
3. Browse the explorer and details panes
If no domain crawl data exists for your project, you will see an empty state with a link to configure domain crawling.
## Sitemap Tree
The left panel organizes your crawled pages into a collapsible folder tree. Pages are grouped by domain and URL path segments.
### Tree Structure
A page at `https://example.com/docs/guides/quickstart` appears as:
```
example.com/
docs/
guides/
quickstart
```
Domain nodes appear at the top level. Path segments create intermediate folder nodes. Leaf nodes represent individual pages.
### Expanding and Collapsing
* Click a **folder node** to expand or collapse it
* Click a **page node** to select it and open the detail panel
* Folders show a page count badge indicating how many pages are nested inside
### Traffic Indicators
Nodes with AI traffic data display small colored badges:
| Badge | Meaning |
| ----------- | -------------------------------------------------------------- |
| Amber badge | Bot crawl events detected on this page or within this folder |
| Green badge | AI referral events detected on this page or within this folder |
Traffic counts aggregate upward through the tree. A folder badge shows the total bot or referral events across all pages inside it.
## Search and Filter
A search bar sits above the tree. Type to filter pages by path or title. The tree updates instantly, hiding nodes that do not match the query.
### Keyboard Shortcut
Press `/` (forward slash) from anywhere on the page to focus the search input. This works as long as you are not already typing in another input field.
### Sort Options
A dropdown next to the search bar lets you sort the tree:
| Sort | Description |
| --------------- | --------------------------------------------- |
| **Path** | Alphabetical by URL path (default) |
| **Bot traffic** | Pages with the most AI bot crawl events first |
| **Referrals** | Pages with the most AI referral events first |
| **Relevance** | Pages with the highest relevance score first |
| **Words** | Pages with the highest word count first |
Sorting applies to leaf nodes within each folder. Folder structure remains stable.
## Page Detail Panel
Selecting a page opens the detail panel with a header and three tabs.
### Header
The header displays:
* **Page title** (or path if no title was extracted)
* **Page type badge** (e.g., article, landing page, documentation)
* **URL** as a clickable link that opens the live page in a new tab
* **Word count** and **token count**
* **Crawled date** showing when this version was last captured
### Content Tab
The Content tab displays the full page content rendered as markdown. This is the same content that AI platforms process when they index your page.
Features:
* **Rich formatting** - Headings, lists, tables, code blocks, blockquotes, and links render with proper styling
* **Topic tags** - If DevTune classified the page into topics, colored tags appear above the content. Tags with high confidence (80%+) show their confidence percentage.
* **Plain text detection** - If the extracted content has minimal markdown formatting, a notice appears indicating the content was captured as plain text
The Content tab loads on demand when you select a page. A loading spinner appears while content is fetched.
### Traffic Tab
The Traffic tab shows AI traffic data for the selected page over the last 28 days:
* **Total events** bar showing the proportion of bot crawls vs. AI referrals
* **Bot Crawls** card with the count of AI bot visits
* **AI Referrals** card with the count of visitors arriving from AI platforms
If no AI traffic has been recorded for the page, a placeholder message appears.
Traffic data comes from DevTune's AI Traffic tracking snippet. It is loaded as part of the initial page data, so switching to the Traffic tab is instant.
## AEO Health Report
The AEO health report summarizes technical crawlability across your primary domains. Expand a domain to see its checks, findings, remediation guidance, and affected URLs. The report helps you connect page-level crawl data with site-level issues such as blocked AI crawlers, missing sitemaps, thin extracted content, missing metadata, or weak sitemap freshness signals.
For the full check list and remediation workflow, see **[Technical AEO Audit](/content-explorer/aeo-audit)**.
## Empty State
If your project has no crawled domain content, Owned Content displays:
* A prompt explaining what the workspace does
* Guidance to configure and start domain crawling first, then wait for the next crawl and optionally enable AI Traffic for better downstream context
Once you run your first domain crawl and it completes, Content Explorer populates automatically.
## Tips
### Finding Specific Pages
Use the search bar to quickly locate pages. The filter matches against both the URL path and the page title, so searching for "quickstart" will find a page at `/docs/getting-started/quickstart` even if it is deeply nested.
### Identifying Thin Content
Sort by **Words** to find pages with the lowest word counts. Thin pages may not provide enough content for AI platforms to index effectively.
### Spotting High-Traffic Pages
Sort by **Bot traffic** to see which pages AI bots visit most frequently. High bot traffic pages are your most important content for AI visibility. Review these pages in the Content tab to ensure they present your information clearly.
### Reviewing Topic Coverage
Open pages in the Content tab and check the topic tags. If important pages are missing topic classifications, the content may not be structured clearly enough for AI platforms to categorize.
## Next Steps
* **[Version History](/content-explorer/version-history)** - Compare page versions and track content changes
* **[Technical AEO Audit](/content-explorer/aeo-audit)** - Understand the domain-level AEO health report
* **[Owned Content Overview](/content-explorer/overview)** - Understand the feature and its purpose
* **[AI Demand Dashboard](/ai-traffic/dashboard)** - See AI demand trends across your entire site
# Owned Content Overview
Source: https://docs.devtune.ai/content-explorer/overview
Browse your crawled site tree, inspect page details, compare versions between crawls, and see which pages AI bots crawl and reference most often.
Owned Content is the workspace for reviewing your crawled site footprint. Its main interface, Content Explorer, organizes pages into a searchable sitemap tree, shows rendered page content, tracks version history across crawls, surfaces AI traffic data per page, and reports technical AEO health for your primary domains.
## What Owned Content Answers
Owned Content helps answer three practical questions:
1. **What content do AI platforms actually see on my website?**
2. **What changed between crawls?**
3. **Which pages get the most AI bot attention or AI referral traffic?**
4. **Are there technical crawlability issues that could stop answer engines from using my content?**
## Why Content Explorer Matters
### See your site through AI eyes
The rendered markdown that Content Explorer displays is the content extracted from your site for crawler-oriented analysis. Reviewing this content helps you:
* Spot rendering or extraction issues
* Audit content quality and structure
* Understand what AI systems are likely to consume
### Connect content to traffic
Owned Content pairs page content with AI traffic signals so you can see whether the pages getting crawled or cited are also the pages getting visited.
### Monitor material change over time
Owned Content keeps the latest crawled page fast to browse, and stores history snapshots when a page is first observed or when a later crawl detects a material content change. This keeps the timeline focused on meaningful changes instead of duplicate crawl records.
### Audit technical AEO health
The AEO health report checks whether AI crawlers and answer engines can discover, fetch, extract, and understand your primary brand domains. It combines existing crawl data with lightweight live checks for crawler access, sitemaps, homepage HTML, metadata, sitemap freshness, markdown extraction, and optional `llms.txt` guidance.
Each domain gets its own score, findings, affected URLs where available, remediation advice, and copyable agent prompts for website-scoped fixes.
## Layout
The main Content Explorer interface uses a two-pane workspace:
### Explorer pane
The left pane shows a collapsible sitemap tree organized by domain and path. It includes:
* Search / filter
* Sorting by **Path**, **Bot traffic**, **Referrals**, **Relevance**, or **Words**
* Page-level traffic badges
### Details pane
The right pane shows the selected page and its metadata, then lets you switch between:
| Tab | What It Shows |
| ----------- | -------------------------------------------------------------------------- |
| **Content** | Rendered markdown content with headings, lists, code blocks, and structure |
| **History** | Version timeline showing baseline and material content-change snapshots |
| **Traffic** | AI bot crawl and AI referral context for the selected page |
## How It Works
1. You configure the relevant owned domains and project setup
2. DevTune crawls the website and extracts markdown content from each page
3. Content Explorer builds a sitemap tree from the crawled pages
4. DevTune runs technical AEO checks after crawls and on a regular refresh schedule
5. Each page can then be inspected for content, history, traffic context, and related AEO findings
## Prerequisites
Owned Content requires crawled domain data. If no pages have been crawled yet, the page shows an empty state that points you back toward configuration and refresh.
## Getting Started
1. **[Browse Content](/content-explorer/browsing-content)** - Navigate the tree, search pages, and inspect page details
2. **[Technical AEO Audit](/content-explorer/aeo-audit)** - Understand scores, checks, findings, and remediation prompts
3. **[Version History](/content-explorer/version-history)** - Compare page versions and track changes
## Next Steps
* **[Browsing Content](/content-explorer/browsing-content)** - Learn how to navigate and search the sitemap tree
* **[Technical AEO Audit](/content-explorer/aeo-audit)** - Review crawler-readiness checks and remediation guidance
* **[Version History](/content-explorer/version-history)** - Understand the version timeline and diff viewer
* **[AI Demand](/ai-traffic/overview)** - Track retrieval evidence and the visible referral tail across your site
# Version History & Diffs
Source: https://docs.devtune.ai/content-explorer/version-history
Track owned content changes across DevTune domain crawls with a visual page version timeline and side-by-side diff comparison between any two crawl snapshots.
DevTune keeps a fast latest copy of each crawled page, then saves historical snapshots when a page is first observed or when a crawl detects a material content change. The History tab in Owned Content shows those snapshots as a visual timeline and lets you compare versions side-by-side.
## Version Timeline
Select a page in the sitemap tree, then click the **History** tab to see its version timeline.
### Timeline Layout
Versions appear in a vertical timeline ordered from newest to oldest. Each version shows:
| Element | Description |
| -------------------- | ------------------------------------------------- |
| **Date and time** | When this version was crawled |
| **Word count** | Total words in the page at this point in time |
| **Change indicator** | Whether content changed from the previous version |
| **Latest badge** | Marks the most recent version |
### Change Indicators
The timeline uses visual cues to show what changed between consecutive versions:
* **Green arrow up** with a positive number - Content was added (word count increased)
* **Red arrow down** with a negative number - Content was removed (word count decreased)
* **Blue equals** with "structure changed" - The content hash changed but the word count stayed the same, indicating structural changes like reformatted headings or reordered sections
* **"no changes"** in muted text - Reserved for snapshots with matching content hashes
### Node Markers
Timeline nodes use different visual styles:
* **Solid primary dot** - The latest (most recent) version
* **Smaller primary dot** - A version where content changed from the prior crawl
* **Hollow circle** - A version with no content changes
### Single Version
If only one version exists, the timeline shows the baseline snapshot. This can mean the page has only been crawled once, or that later crawls did not produce a material content change.
## Comparing Versions
Each version in the timeline (except the oldest) has a **Compare with previous** button. Clicking it opens a full-screen dialog with a side-by-side diff.
### Diff Viewer
The diff dialog shows:
* **Stats bar** at the top with lines added (green), lines removed (red), and net word count change
* **Side-by-side diff** powered by a code-diff renderer, with added lines highlighted in green and removed lines highlighted in red
* **File labels** showing the page URL and the date of each version
The diff viewer treats page content as markdown text. It highlights line-level additions and removals, making it straightforward to see exactly what changed between two crawls.
### Reading the Diff
* **Green highlighted lines** are content that was added in the newer version
* **Red highlighted lines** are content that was removed from the older version
* **Unchanged lines** provide context around the changes
The stats bar provides a quick summary:
| Stat | Meaning |
| ------------------------ | ------------------------ |
| `+N` (green) | Number of lines added |
| `-N` (red) | Number of lines removed |
| `+N words` or `-N words` | Net change in word count |
## Use Cases
### Tracking Content Updates
After updating pages on your website, run a new domain crawl and check Owned Content to verify the changes were captured correctly. The diff viewer confirms exactly what AI platforms will see in the updated content.
### Monitoring Competitor Content Changes
If your domain crawl configuration includes competitor domains, use the version timeline to track how their content evolves over time. Word count trends and change frequency reveal how actively a competitor maintains their content.
### Identifying Unintended Changes
Sometimes website deployments introduce unintended content changes (broken formatting, stripped sections, duplicated text). The diff viewer helps you spot these issues by comparing the pre-deployment and post-deployment crawl snapshots.
### Auditing Content Freshness
The version timeline shows the crawl date for each snapshot. Pages that have not changed across multiple crawls may need updates. Sort the tree by relevance or bot traffic to prioritize which stale pages to refresh first.
## How Versions Work
### What Creates a New Version
DevTune does not store a full duplicate version for every crawl. A new history snapshot is created when:
* The page is first observed
* The extracted page content changes enough to pass material-change filtering
Crawls that see the same content, or only minor extraction drift, update the latest page state without adding noise to the version timeline.
### Content Hash
DevTune computes a content hash for each crawled page body. Hash differences are then checked against a materiality filter so small crawler or rendering differences do not automatically become visible page changes. Two snapshots can have the same word count but different hashes if text was reworded without changing length.
### Data Retention
Material page snapshots are retained for history and diffing. The current page row remains optimized for fast browsing, while historical content is kept separately so the Owned Content list does not scan large version history.
## Troubleshooting
### No History Available
If the History tab shows "No version history available," the page may not have version data associated with it. This can happen if:
* The page was crawled before snapshot history was available and has not been backfilled
* There was a data issue during the crawl
### Only One Version
A single baseline version is normal when later crawls have not detected a material content change.
### Diff Shows Unexpected Changes
If the diff shows large-scale changes that do not match your actual content edits, the cause is usually:
* **Rendering differences** - Dynamic content (dates, personalized elements) changes on every crawl
* **JavaScript loading variations** - Single-page app content may render slightly differently between crawls
* **Third-party embeds** - Embedded widgets and ads can inject different content each time
## Next Steps
* **[Browsing Content](/content-explorer/browsing-content)** - Navigate the tree and view page details
* **[Owned Content Overview](/content-explorer/overview)** - Understand the feature and how it fits into DevTune
* **[AI Demand](/ai-traffic/overview)** - Track retrieval evidence and the visible referral tail across your site
# Creating Your Account
Source: https://docs.devtune.ai/getting-started/creating-account
Step-by-step guide to creating a DevTune account with email, Google, or GitHub sign-up, choosing a plan, and setting up your team workspace.
Getting started with DevTune is quick and easy. This guide walks you through the account creation process.
## Sign Up Options
DevTune offers three ways to create your account:
### Email and Password
1. Visit [devtune.ai](https://devtune.ai) and click **Get Started**
2. Enter your email address and create a password
3. Check your inbox for a verification email
4. Click the verification link to activate your account
### Google
1. Visit the sign-up page and enter your email address
2. Choose **Continue with Google**
3. Complete Google authentication
4. You will be signed in and redirected to onboarding
### GitHub
1. Visit the sign-up page and enter your email address
2. Choose **Continue with GitHub**
3. Complete GitHub authentication
4. You will be signed in and redirected to onboarding
## After Signing Up
Once your account is created, you'll be guided through an onboarding flow:
1. **Create or join a team** - DevTune projects live inside team accounts, so you'll create a new team or accept an invitation to join an existing one
2. **Create your first project** - The onboarding wizard walks you through setting up your first project in five steps
## Team Accounts
DevTune is designed for teams. When you create an account, you can:
* **Create a new team** - Start a team workspace and invite colleagues
* **Join an existing team** - Accept an invitation from a team member
### Team Benefits
* Share projects across your organization
* Collaborate on tracking configurations
* Unified billing at the team level
* Role-based access control (Owner and Member roles)
## Account Types
### Personal Account
Your personal account is created automatically when you sign up. It's used for:
* Managing your profile and settings
* Accessing team workspaces you're invited to
### Team Account
Team accounts are shared workspaces where your actual projects live. Teams provide:
* Project organization and management
* Member management with role-based permissions
* Collaborative features across your organization
> **Note:** Most DevTune features and projects are managed at the team level, not the personal account level.
## Choosing a Plan
View current plans and limits on the **[Pricing page](https://devtune.ai/pricing)**.
## Next Steps
After creating your account:
1. **[Create Your First Project](/getting-started/first-project)** - Walk through the onboarding wizard
2. **[Invite Team Members](/account-billing/team-management)** - Collaborate with your team
3. **[Explore the Dashboard](/getting-started/dashboard-overview)** - Learn your way around
# Account Home and Project Layout
Source: https://docs.devtune.ai/getting-started/dashboard-overview
Get oriented with the DevTune dashboard: the Account Home project list, project sidebar sections, and the main navigation between team and project surfaces.
This guide explains how DevTune is organized once you are inside a team account and a project.
> **DevTune 2.0:** Project navigation follows the Visibility → Traffic → Act → Outcomes loop. Adoption is retired, while the legacy Alerts and Timeline routes open **Outcomes → Timeline**. Accounts on the legacy experience retain the older sidebar entries described below.
## Account Home
When you sign in, you'll land on your **Account Home** page. This is your central hub showing:
* **All your projects** displayed as cards
* **Quick access** to create new projects
* **Search functionality** to find projects quickly
Each project card shows:
* Project name and description
* Quick stats and recent activity
* Visibility and usage signals
Click any project card to enter that project's workspace.
## Project Navigation
Once inside a project, you'll see a sidebar with the following sections:
### Overview
* **Actions** - Your workspace for suggestions and backlog work
* **Outcomes** - Completed work, measured impact, attribution, and project event history on the Timeline tab in the 2.0 experience
* **Alerts** - Legacy notifications and project event history page
* **Timeline** - Legacy cross-signal chronology of community activity, content changes, annotations, and outcomes
### Signals
* **AI Search** - Search visibility workspace with tabs for Dashboard, Prompts, Citations, Competitors, and Analytics
* **Adoption Metrics** - Legacy package and repository adoption trends
* **Community Discourse** - Discussion signals from Reddit, GitHub, Hacker News, Stack Overflow, Dev.to, and related sources
* **Owned Content** - Crawled pages, version history, and page-level AI traffic
* **AI Demand** - What AI systems retrieve and cite, plus the visible referral tail
### Settings
* **Project Settings** - Centralized configuration with tabs for General, Brands, Platforms, Content Preferences when enabled, and AI Traffic
## Top Navigation
At the top of every page you'll find:
* **Project selector** - Switch between projects quickly
* **Team selector** - Switch between team accounts if you belong to multiple
* **Notifications** - View alerts and updates
* **Account menu** - Access settings and sign out
## Key Metrics at a Glance
Throughout the workspace, you'll encounter a few recurring metric families.
### AI Search metrics
* **Overall Presence Rate** - How often completed AI Search responses cite a URL tracked to your brand
* **Share of Voice** - Your relative citation and mention share versus tracked competitors
* **Brand Mentions** - How often your brand is named directly in response text
* **Primary Citation Share** - How often your tracked sources are the cited sources, not just mentioned
### Community and traffic metrics
* **Threads / replies** - How much relevant discussion volume is happening in community channels
* **Source overlaps** - Threads that overlap with your tracked or AI-cited URLs
* **AI bot visits / AI referrals** - Which AI platforms crawl your site and send traffic
## Quick Actions
From the project workspace, you can quickly:
* **Review Suggestions** - Check active recommendations for improving visibility
* **Review Backlog and Outcomes** - See what your team has adopted, then measure shipped work in the Outcomes stage
* **Check Outcomes Timeline** - Review measured changes and project events; legacy accounts can continue using Alerts
* **Open Project Settings** - Update brands, URLs, terms, platforms, content preferences when enabled, and AI traffic configuration
## Mobile Experience
DevTune is optimized for desktop use, but you can still:
* View results and analytics on mobile
* Check notifications and project events in Outcomes Timeline, or Alerts in the legacy experience
* Review high-level dashboards
For detailed configuration, we recommend using a desktop browser.
## Next Steps
* **[Create Your First Project](/getting-started/first-project)** - Set up your tracking workspace
* **[Understand Key Concepts](/getting-started/key-concepts)** - Learn DevTune terminology
* **[Explore AI Search Metrics](/search-tracking/visibility-metrics)** - Understand your visibility metrics in depth
# Creating Your First Project
Source: https://docs.devtune.ai/getting-started/first-project
Complete guide to setting up your first DevTune project using the onboarding wizard, including brands, tracked URLs, prompts, and AI Search platforms.
A project in DevTune is your workspace for one product or brand. This guide walks you through creating your first project using the onboarding wizard.
## Starting the Project Wizard
There are two ways to create a project:
1. **During onboarding** - After creating your account and team, you'll be guided directly into the project creation wizard
2. **From Account Home** - Click **Create Project**
## Project Setup Steps
The wizard walks you through five steps.
### Step 1: Product Basics
Enter your project name and your product's website URLs.
**Project name** should be clear and descriptive, for example:
* "Acme Analytics"
* "CloudSync Platform"
* "DataFlow API"
**Website URLs** should include the main properties that represent the product:
* Main website
* Documentation
* Any other relevant product surface
DevTune uses these URLs to generate the initial product context.
### Step 2: Review AI-Generated Context
DevTune analyzes the URLs you provided and generates a product context description. Review and edit it so it accurately explains:
* What problem your product solves
* Who your target users are
* Key features and capabilities
* What category of tool it is
Better context leads to better prompt suggestions and stronger recommendations later.
### Step 3: Add Competitors
Add at least one competitor brand to enable Share of Voice and competitive comparisons.
For each competitor, provide:
* **Competitor name**
* **Relevant URLs or domains**
You can expand or refine competitors later from **Project Settings > Brands**.
### Step 4: Select Prompts
DevTune suggests relevant prompts based on your product context. Review the suggestions and select the ones you want to track.
Good starter prompts usually include:
* Category discovery prompts
* Evaluation / comparison prompts
* Integration prompts
You can add or revise prompts later from **AI Search > Prompts**.
### Step 5: Run AI Search
The final step kicks off your first AI Search run. DevTune queries the AI platforms enabled for your plan and collects the baseline results.
Platform coverage depends on your plan:
* **Starter / Plus** - ChatGPT, Perplexity, Gemini
* **Pro and above** - ChatGPT, Perplexity, Gemini, Google AI Mode, Microsoft Bing Copilot
## What Happens After Creation
Once the initial run completes:
1. You can open the **AI Search Dashboard** to review the baseline
2. DevTune starts generating recommendations in **Actions**
3. Ongoing runs populate trends over time
## Editing Project Settings
After creation, use **Project Settings** for ongoing setup:
* **General** - Project name, description, product context
* **Brands** - Brands, tracked URLs, brand terms
* **Platforms** - Enabled AI Search engines
* **AI Traffic** - Tracking snippet setup
## Project Organization Tips
### One project per product
Create separate projects for distinct products, even if they belong to the same organization.
### Keep context current
If the product positioning changes, update **Project Settings > General** first. If the content footprint changes, update **Project Settings > Brands**.
## Next Steps
1. **[Explore Your Dashboard](/getting-started/dashboard-overview)** - Learn the interface
2. **[Understand Key Concepts](/getting-started/key-concepts)** - Learn DevTune terminology
3. **[Open Actions](/insights-actions/actions-hub)** - Review AI-powered recommendations
# DevTune Key Concepts and Terminology
Source: https://docs.devtune.ai/getting-started/key-concepts
Reference for core DevTune concepts: projects, prompts, brands, tracked URLs, citations, share of voice, presence rate, and AI Search visibility metrics.
Before diving deeper into DevTune, it helps to understand the key concepts and terminology used throughout the platform.
## Core Concepts
### Projects
A **project** is your workspace for tracking one product or brand. Projects contain:
* Tracked prompts
* Brands, tracked URLs, and brand terms
* AI Search configuration
* Community Discourse and Owned Content context
* Actions workspace, briefs, and backlog
* Outcomes measurement, attribution, and timeline evidence
### Product Context
**Product context** is the structured description of what your product does. During project creation, DevTune generates this automatically from your website URLs. You can review and edit it later from **Project Settings > General**.
Good product context leads to better prompt suggestions and more relevant recommendations.
### Brands
**Brands** are the organizational concept for competitive tracking. Each project has:
* A **primary brand** - your product or company
* **Competitor brands** - the brands you want to compare against
Each brand has associated tracked URLs and brand terms that DevTune uses to identify citations and mentions in AI responses.
## AI Search Concepts
### AI Search Platforms
DevTune monitors your visibility across AI-powered search platforms. The platforms available depend on your plan tier:
* **ChatGPT** - Starter and above
* **Perplexity** - Starter and above
* **Gemini** - Starter and above
* **Google AI Mode** - Pro and above
* **Microsoft Bing Copilot** - Pro and above
### Prompts
**Prompts** are the search queries you want to track across AI platforms. These are the kinds of questions users might ask when looking for solutions your product provides.
Prompts are managed from the **AI Search > Prompts** tab.
### Brand Terms
**Brand terms** are the text terms DevTune monitors for brand mentions in AI responses. These typically include your product name, company name, and common variations or abbreviations.
Brand terms are configured per brand from **Project Settings > Brands**.
### Tracked URLs
**Tracked URLs** are the domains and URLs DevTune monitors when they appear as citations in AI Search results. This typically includes:
* Your marketing website
* Your documentation site
* Your GitHub repository
* Competitor properties
Tracked URLs are managed per brand from **Project Settings > Brands**.
### Citations
**Citations** track when AI Search results link to specific URLs. This shows which of your pages are being referenced and how prominently they appear.
## Key Metrics
### Primary KPIs
These are the top-level metrics that summarize your AI Search visibility:
* **Overall Presence Rate** - The percentage of completed AI Search responses that cite at least one URL tracked to your brand
* **Share of Voice** - Your brand's share of total mentions and citations compared to competitors
* **Sentiment Score** - How positively or negatively AI platforms describe your brand when they mention it
### Secondary Metrics
These provide deeper insight into specific aspects of your visibility:
* **Docs Presence**
* **Blog Presence**
* **Brand Mentions**
* **Top of Answer**
* **Avg Citation Rank**
* **Primary Citation Share**
The Brand Mentions metric is separate from Overall Presence Rate: an uncited text mention of your brand contributes to Brand Mentions, but not to Overall Presence Rate.
## Community Discourse Concepts
### Threads and Replies
Community Discourse tracks relevant discussions and their useful replies across supported developer communities.
### Source Overlaps
**Source overlaps** are threads that contain exact matches with your tracked URLs or URLs already being cited in AI Search.
### Clusters
**Clusters** are discussions where your primary brand and tracked competitors appear together, making them useful for competitive analysis.
## AI Demand Concepts
### AI Bot Crawlers
**AI bot crawlers** are automated agents from AI platforms such as GPTBot or ClaudeBot that visit your website to index content.
### AI Referral Traffic
**AI referral traffic** consists of human visitors who arrive at your website after clicking a link in an AI-generated response.
### Tracking Snippet
The **tracking snippet** is the lightweight JavaScript snippet you install from **Project Settings > AI Traffic** to collect AI traffic data.
## Actions Concepts
### Suggestions
**Suggestions** are evidence-backed recommendations generated from the current state of your project.
### Briefs
A **brief** is a reusable execution artifact generated from a suggestion. Brief generation uses content credits.
### Content Credits
**Content credits** power brief generation and related content workflows:
* Your account holds one credit balance
* The plan's monthly allowance funds it each billing anniversary and expires at the end of that month
* Purchased add-on credits fund the same balance and never expire
* Spending takes the expiring allowance first, so bought credits are what remain
* Automatic brief prewarming only uses a capped portion of the monthly allowance
## Team Concepts
### Team Account
A **team account** is the shared workspace where projects are managed.
### Roles
DevTune has two primary roles:
* **Owner** - Full access including billing management, team settings, member management, and role management
* **Member** - Access to projects and analytics, with broad collaboration permissions
## Next Steps
* **[Create Your First Project](/getting-started/first-project)** - Set up your tracking
* **[Explore the Dashboard](/getting-started/dashboard-overview)** - Learn your way around
* **[Understand Visibility Metrics](/search-tracking/visibility-metrics)** - Dive deeper into metrics
# Quickstart Guide
Source: https://docs.devtune.ai/getting-started/quickstart
Get started with DevTune in 5 minutes: create your first project, add prompts, run AI Search tracking, and understand your visibility metrics and citations.
Welcome! This guide will get you from zero to useful recommendations in about 5 minutes. Let's get your AI search visibility tracking set up.
## What You'll Accomplish
By the end of this guide, you'll have:
* Created your first DevTune project
* Added prompts to track your brand in AI search
* Run your first AI search tracking test
* Understood your key visibility metrics
## Step 1: Create Your Account (1 minute)
If you haven't already, [sign up for DevTune](https://devtune.ai/auth/sign-up). The Starter plan includes a 7-day free trial to get you started.
After signing up and creating or joining a team, you'll be taken to the project creation wizard.
## Step 2: Create Your First Project (3 minutes)
The project wizard guides you through five steps:
### Step 2a: Product Basics
Enter your project name and website URLs. Choose a clear name that represents what you're tracking. For example:
* "Acme Analytics"
* "My SaaS Product"
* "Company Website"
Add the URLs for your product's website, documentation, or other web properties. DevTune uses these to generate product context automatically.
### Step 2b: Review AI-Generated Context
DevTune analyzes your website URLs and generates a product context description. Review the AI-generated context and edit it if needed. This context helps DevTune understand your product and generate relevant prompts.
**Good product context includes:**
* What problem your product solves
* Who your target users are
* Key features and capabilities
* What category or type of tool it is
### Step 2c: Add a Competitor
Add at least one competitor brand and their domains. This enables Share of Voice comparisons and competitive analysis from your first test run.
### Step 2d: Select Prompts
DevTune suggests relevant prompts based on your product context. Select the prompts you want to track across AI platforms.
**Good prompts to start with:**
* "What's the best \[your category] tool?"
* "How do I \[common task your product solves]?"
* "Compare \[your product] vs \[competitor]"
> **Tip:** Start with 5-10 prompts. You can always add more later from **AI Search > Prompts** or by refining your project setup in **Project Settings**.
### Step 2e: Run Test
Your first AI search tracking test runs as the final step of the wizard. DevTune will query AI platforms with your selected prompts.
The available platforms depend on your plan tier:
* **Starter / Plus** - ChatGPT, Perplexity, Gemini
* **Pro and above** - ChatGPT, Perplexity, Gemini, Google AI Mode, Microsoft Bing Copilot
This typically takes 2-5 minutes depending on how many prompts you have.
## Step 3: Understand Your Results
Once your test completes, you'll see your dashboard with key metrics:
### Overall Presence Rate
The percentage of AI search responses where your tracked URLs appear. This is your primary visibility metric showing how often AI platforms reference your content.
### Share of Voice
Your brand's share of all citations across tracked prompts, compared to competitors. This shows your relative market position in AI search.
### Sentiment Score
How positively or negatively AI platforms describe your brand when they mention it. Higher scores indicate more favorable mentions.
### Secondary Metrics
As you explore deeper, you'll also find:
* **Brand Mentions** - How frequently your brand name appears directly in AI response text
* **Top of Answer** - The percentage of times your domain appears as the first citation
* **Avg Citation Rank** - Your average citation position when cited (lower is better)
* **Primary Citation Share** - How often you are the primary citation among all cited sources
## What's Next?
Now that you have your first results:
1. **Review Suggestions** - Look at the actions workspace for evidence-backed recommendations
2. **Set Up Alerts** - Get notified when your visibility changes significantly
3. **Review Analytics and Prompts** - Use the AI Search tabs to inspect trends, citations, and prompt-level performance
4. **Check Back Regularly** - DevTune runs automatic scheduled scans to track trends over time
## Key Terms Glossary
| Term | Definition |
| ------------------------- | -------------------------------------------------------------- |
| **Project** | Your workspace for tracking a specific product or brand |
| **Prompt** | A search query monitored across AI platforms |
| **Brand Terms** | Terms monitored for brand mentions in AI responses |
| **Tracked URL** | A tracked domain that may appear as a citation in AI responses |
| **Citation** | When an AI platform references a URL in its response |
| **Overall Presence Rate** | Percentage of responses where your tracked URLs appear |
| **Share of Voice** | Your brand's percentage of all citations for tracked prompts |
| **Sentiment Score** | How positively AI platforms describe your brand |
## Need Help?
* **Questions?** Reply to any email from us - we read and respond to everything
* **Check our docs** - Browse the full [documentation](/introduction) for detailed guides
Happy tracking!
# Working with Actions
Source: https://docs.devtune.ai/insights-actions/actions-hub
Turn DevTune signals into shipped work in the Actions workspace: review ranked suggestions, generate briefs, and manage your backlog.
The Actions workspace is where DevTune recommendations become real work. It combines active suggestions and your adopted backlog in one project-level workflow. The separate **Outcomes** stage measures completed work after it ships.
## The two Actions surfaces
### Suggestions
Suggestions are active recommendations ranked by evidence and opportunity. This is the place to review what DevTune thinks is worth doing next.
Typical actions from a suggestion:
* **Generate brief** for a fuller execution plan
* **Add to backlog** when you want to commit to the work
* **Use existing asset** when an owned page already covers the need
* **Snooze** when the idea is valid but not timely
* **Dismiss** when it is not relevant
### Backlog
Backlog contains work your team has chosen to do. This includes:
* Suggestions you adopted from the feed
* Manual actions your team created directly
## Outcomes stage
Open **Outcomes** from the project sidebar to review completed work and what changed after it shipped.
When you mark an Action as **Done**, DevTune automatically creates an **intervention** that tracks:
* The specific URL you targeted (if any)
* Baseline citation metrics before your change
* A snapshot of the page content at completion
After subsequent domain crawls, DevTune compares new citation counts to your baseline. If citations increased, the intervention is marked as **correlated** — meaning the increase happened after the Action and may indicate a positive visibility change worth reviewing.
This lets you answer: *"Did this work actually move the needle?"*
#### Outcome Markers vs Completed Actions
In the Outcomes stage, you'll see **outcome markers** on timeline charts. These are distinct from the Actions themselves:
* **Completed Actions** are the work items you finished (e.g., "Create comparison page")
* **Outcome markers** are visual indicators on the timeline showing:
* **Action completed** (blue dot) — When you marked the Action Done for this URL
* **Change detected** (amber/green dot) — When domain crawls later detected content changes on that same URL
A single Completed Action creates one action-completed marker. But a URL can have multiple markers over time — your initial completion, followed by detected changes during subsequent crawls. This helps visualize the timeline of activity on specific pages.
The cross-signal Timeline also shows **post-change page citations**. Those are primary citations to pages after crawl-detected content changes. They can appear even when no Actions have been accepted into the backlog, while the Outcomes stage remains focused on completed/intervention-backed work.
## Accessing the Actions workspace
Navigate to **Actions** in your project sidebar. Inside the page, switch between **Suggestions** and **Backlog**. Use the separate **Outcomes** sidebar stage to review measured results.
## Generate Brief
Use **Generate brief** to get a fuller recommendation, based on current evidence, related owned content, and relevant external page context, before you commit work.
### Content credits
Brief generation spends from your account's single credit balance:
* **Automatic prewarming** prepares briefs for some high-priority suggestions so they open faster. It draws on a limited automatic allowance, so it cannot spend the whole balance.
* **Manual generation** happens when you click **Generate brief** or **Regenerate brief**. It spends from the balance directly.
Spending takes the expiring monthly allowance before purchased credits.
If a brief is marked **Stale**, DevTune keeps the existing brief visible so you can still use or copy it. You can manually regenerate it when you want a fresh version.
### Brief style and content preferences
By default, DevTune generates each brief in the best-fit format for the action. Some actions also offer a brief-style selector so you can request a specific format.
If project content preferences are enabled, the selector only offers formats allowed for that project. DevTune also uses the same preferences when it recommends new content actions. Blocked formats are not intentionally recommended, and manual requests for a blocked brief style are rejected instead of being generated.
## Action Properties
### Title
A clear, descriptive name for the action, such as:
* "Create getting started guide for Python SDK"
* "Improve API reference documentation structure"
* "Add comparison page: our product vs. Competitor X"
### Description
Detailed information including:
* What needs to be done
* Why it matters
* Success criteria
* Relevant evidence and context
### Status
Backlog actions follow a defined workflow:
| Status | Meaning |
| ----------- | ------------------------------------------ |
| Backlog | Committed work that has not started yet |
| In Progress | Currently being worked on |
| Blocked | Waiting on a dependency or external factor |
| Done | Finished |
| Canceled | No longer being pursued |
### Priority
Importance and urgency level:
| Priority | Meaning |
| -------- | -------------------------------- |
| Urgent | Requires immediate action |
| High | Do soon, high impact expected |
| Medium | Important but not time-sensitive |
| Low | When resources allow |
### Channel
Actions are routed to the appropriate team or function:
| Channel | Description |
| ----------- | ------------------------------------- |
| docs | Documentation improvements |
| content | Blog posts, guides, marketing content |
| devrel | Developer relations and community |
| pr | Public relations and communications |
| engineering | Technical infrastructure changes |
| product | Product feature or design changes |
| other | Actions that do not fit other buckets |
### Source
Where the action came from:
* **Generated recommendation** - Created from DevTune's evidence-backed recommendation engine
* **Manual** - Created directly by a team member
## Working through a suggestion
### Add to backlog
Use **Add to backlog** when the team wants to do the work. The recommendation leaves the suggestion feed and becomes a real backlog item.
### Use existing asset
Use **Use existing asset** when the recommendation is already covered by an owned page or doc. Link the relevant asset so DevTune can suppress the suggestion unless the evidence changes materially.
### Snooze or dismiss
* **Snooze** is for valid ideas that should resurface later
* **Dismiss** is for ideas that should not come back unless the evidence materially changes
## Creating manual actions
To create an action directly:
1. Go to **Actions**
2. Click **Add Action**
3. Fill in the title, description, priority, and channel
4. Set the initial status
5. Save
## Managing Actions
The workspace surfaces:
* Active suggestions
* Backlog items organized by execution status
* Priority indicators
* Channel labels
* Source type indicators
* Query-cluster and evidence context where available
## Recommended Process
1. **Review suggestions** - Identify valuable recommendations
2. **Generate briefs where needed** - Gather enough context to make a decision
3. **Add the best items to backlog** - Commit to work
4. **Create manual actions when needed** - Capture work that did not start as a suggestion
5. **Prioritize and route** - Set priority and assign the right channel
6. **Execute** - Do the work
7. **Complete and measure** - Mark it done and review impact in the Outcomes stage
## Best Practices
* Triage suggestions regularly so backlog stays meaningful
* Keep actions specific and reasonably scoped
* Review outcomes to understand which work actually moved your signals
## Next Steps
* **[Alerts](/insights-actions/alerts)** - Get notified of important events
* **[Analytics](/analytics/overview)** - Measure the impact of completed actions
# Alerts & Notifications
Source: https://docs.devtune.ai/insights-actions/alerts
Configure DevTune project alerts for visibility regressions, competitor threats, and weekly digests, and review the per-project notification history.
Alerts help you stay aware of important changes without living inside the app. DevTune separates immediate interruptions from scheduled digests so you can tune noise more deliberately.
> **DevTune 2.0:** Alert configuration, email delivery, and the in-app notification bell remain available. Project event history now lives in **Outcomes → Timeline**. Accounts on the legacy experience retain the project **Alerts** page.
## What are Alerts?
Alerts are notifications triggered by events or conditions in your project:
* **Coverage regressions** - Material drops in overall AI visibility, share of voice, or top-of-answer performance
* **Docs / source regressions** - Your docs or source pages are showing up less often on prompts your team can improve
* **Competitor threats** - A competitor is gaining enough momentum to warrant attention
* **Scheduled digests** - Weekly summaries and actions digests
* **Collaboration alerts** - @mentions in action comments
## Alert Types
### Immediate Alerts
Immediate alerts are for events that may need prompt attention.
#### Coverage Regression
Use when you want an immediate alert for meaningful drops in core visibility signals.
#### Docs / Source Regression
Use when you want a narrower alert focused on documentation and source coverage your team can directly improve.
#### Competitor Threat
Use when you want to know that a competitor has crossed or escalated beyond a chosen threat level.
### Scheduled Reports & Digests
Scheduled notifications are useful to review, but not worth an interruption.
#### Weekly Summary
A broader account and project summary delivered on a schedule.
#### Actions Digest
A summary of active recommendations and backlog movement across your projects. This can be delivered daily or weekly.
### Collaboration
#### @mentions
Use this when you want direct notifications from teammate interactions inside action comments.
## Notification Channels
DevTune supports two notification channels:
### In-App Notifications
Alerts appear within DevTune:
* Notification icon in the header
* Outcomes Timeline in the 2.0 project experience, or the project Alerts page in the legacy experience
* In-app digest entries
### Email Notifications
Receive alerts via email:
* Configure delivery in your notification settings
* Choose which alert families should email you
* Set digest frequency where supported
## Configuring Alerts
### Notification Settings
Alert preferences are configured in your personal settings inside the team workspace:
1. Open the user menu
2. Go to **User**
3. Select the **Notifications** tab
4. Configure your preferences across these sections:
* **Notification Presets** - Quick starting points for docs, growth / devrel, or founder-style notification bundles
* **Notification Scope** - Account-wide defaults or project-specific overrides
* **Immediate Alerts** - Coverage regression, docs / source regression, and competitor threat
* **Reports & Digests** - Weekly summary and actions digest
* **Collaboration** - @mentions
### Per-Project Overrides
You can configure notification overrides on a per-project basis. This is useful when you want tighter monitoring on one project and lower-noise defaults everywhere else.
### Sensitivity and thresholds
Some alert families have extra controls:
* **Coverage regression** and **Docs / source regression** use a sensitivity setting to control how aggressively incidents open
* **Competitor threat** uses a minimum threat level so you only hear about meaningful competitor movement
* **Actions digest** lets you choose a daily or weekly cadence
## Managing Alert Volume
### Avoiding Alert Fatigue
Too many alerts become noise:
* Focus on the events that truly require your attention
* Set sensitivity and threat levels that filter out minor movement
* Disable alert types that you consistently ignore
### Recommended Setup
Start with:
* Coverage regression enabled
* Competitor threat enabled at a meaningful threshold
* Weekly actions digest enabled
Add more granular alerts as you learn what matters for your workflow.
### Alert Tuning
Adjust over time:
* If receiving too many alerts, lower sensitivity or raise the competitor threat threshold
* If missing important changes, enable more immediate alerts or add a daily digest
* Review alert effectiveness periodically
## Event History
### Viewing Past Alerts
Open **Outcomes → Timeline** in the 2.0 project experience. In the legacy experience, access notification history from the **Alerts** page in your project sidebar:
* All triggered alerts with timestamps
* What triggered each alert
* Link to the relevant project context when available
### Using History
Alert history helps you:
* Understand patterns in visibility changes
* Track how quickly you respond to issues
* Identify recurring problems
* Audit alert effectiveness
## Best Practices
### Start Simple
Begin with essential alerts only:
* Coverage regressions
* Competitor threats
* Weekly or daily actions digests
Expand your alert configuration as you learn what matters for your workflow.
### Focus on Actionable
Only alert on things you will act on:
* Ensure clear next steps exist for each alert type
* Alerts should prompt investigation or action, not just awareness
### Regular Review
Periodically assess your alert configuration:
* Are the alerts you receive useful?
* Are you missing important events?
* Do sensitivity or threat values need adjustment?
### Team Coordination
If multiple team members are on the same team:
* Coordinate who receives which alert types
* Avoid duplicate effort by assigning alert response ownership
* Use the Actions workspace to track responses to alerts
## Troubleshooting
### Not Receiving Alerts
If alerts are not arriving:
* Check that the alert type is enabled in your notification settings
* Verify your email address is correct (for email notifications)
* Check spam/junk folders for email alerts
* Confirm the project is using the expected account-wide or project-specific settings
### Too Many Alerts
If you are overwhelmed:
* Lower sensitivity
* Raise the competitor threat threshold
* Disable low-value alert families
* Rely more on scheduled digests
## Next Steps
* **[Working with Actions](/insights-actions/actions-hub)** - Respond to alerts with tracked work
* **[Personal Settings & Notifications](/account-billing/account-settings#notifications-tab)** - Open the Notifications tab to configure alert preferences
# Outcomes ledger and timeline
Source: https://docs.devtune.ai/insights-actions/outcomes
Review measured actions, before-and-after page signals, content-change links, and the Outcomes timeline.
**Outcomes** shows what happened after completed actions and detected content changes. It uses page-level before-and-after measurements and labels improvements as correlated, not proven.
## Open Outcomes
1. Open a project
2. Select **Outcomes** in the project sidebar
3. Choose **Ledger**, **Attribution**, or **Timeline**
Use the **7 days**, **28 days**, or **90 days** control to choose which measured actions or changes appear. Row deltas always compare the 14 days after a detected change with the 14 days before it; the reporting-window control does not change that comparison.
## Ledger
The **Ledger** tab is the default view. Its scoreboard summarizes:
* **Actions tracked** — measured, in-flight, and unmeasured actions in the selected range
* **Measured wins** — changed pages where citations rose by at least 1, or answer fetches rose by both at least 5 and 25%
* **Win rate** — measured wins divided by measured actions
* **Median time to signal** — time from action completion to measurement
* **Unmeasured** — actions with unmatched URLs or missing sensor coverage
A measured win is a correlation rule: usable measurements must show either a citation increase of at least 1 or an answer-fetch increase of both at least 5 and 25% in the 14 days after the change compared with the 14 days before. A smaller positive change does not count toward **Measured wins** or **Win rate**. A qualifying rise does not prove that the action caused it.
Each ledger row shows the action, measurement status, citations per day, presence change, answer fetches when available, and measurement date. Select a row to open its measured-action detail.
### Status and confidence
Outcomes uses the same status vocabulary throughout the ledger and timeline:
* **Pending detection** — waiting to detect the page change
* **Pending URL match** — no crawled page matches the action links yet
* **Change detected** — the before-and-after window is open
* **Correlated** — a supported signal improved after the change; correlated, not proven
* **No change** — the measurement closed without a qualifying improvement
Confidence describes sensor coverage, not causality:
* **observed** — the sensor covered the full measurement window
* **directional** — the sensor covered part of the window
* **insufficient window** — there was not enough covered time for a complete comparison
* **not observable** — no comparable sensor window exists
Cells use states such as **measuring · day N of 14**, **awaiting next crawl**, and **window open** instead of treating incomplete measurement as zero.
## Measured action detail
Select a ledger row to review:
* The lifecycle from **Action completed** through **Measured**
* Citation and presence changes
* Answer-fetch changes and their sensor basis
* AI referrals as unavailable when no comparable GA4 measurement exists
* A daily page-signals chart with the detected-change marker
* Impact windows for 7, 14, 28, and 90 days
* Content hashes, crawl evidence, and a link to page history
Open windows remain labeled **window open** until enough time has passed.
## Attribution
The **Attribution** tab links detected content changes to completed DevTune actions. The tab name describes that record linkage; its signal deltas remain correlations, not causal attribution.
Use it to:
* Compare detected changes with the actions that claim them
* Find **Unattributed** changes, meaning no completed action currently claims the edit
* Filter changed pages by URL path
* Select **Claim change** to create a completed measured action for an unclaimed change
The table shows 14-day citation and presence deltas for the changed page. **Unattributed lift** is the sum of those page-level citation changes for unclaimed edits; it does not assign the change to a person, campaign, or channel.
## Timeline
The **Timeline** tab places content changes and outcome measurements on one chronology.
* Switch the line between **Presence rate** and **Citations / day**
* Compare that line with **Content changes / day** bars
* Use **Action measured** markers to find completed measurements
* Filter the event feed by **Measurements**, **Changes**, or **Signals**
The feed includes measurement openings and closures, detected and unattributed changes, answer-fetch signals, coverage drops, and URL-match failures. Selecting an event highlights the corresponding point on the chart when one is available.
## Next steps
* [Manage work in Actions](/insights-actions/actions-hub)
* [Inspect page evidence in Audit](/audit/overview)
* [Run a DevTune Agent](/agents/overview)
# Actions Workspace Overview
Source: https://docs.devtune.ai/insights-actions/overview
Learn how DevTune's Actions workspace turns signals and content preferences into evidence-backed recommendations.
DevTune does not stop at showing metrics. The Actions workspace turns AI Search, Community Discourse, Owned Content, adoption, and AI Demand signals into a working queue of evidence-backed recommendations.
The Actions workspace has two main surfaces:
* **Suggestions** - Active recommendations that DevTune believes are worth considering now
* **Backlog** - Work your team has adopted
Alongside the workspace, the **Outcomes** stage measures completed work and the impact it created. In the 2.0 project experience, its **Timeline** tab keeps the project-level event history, while alert preferences still control digest and immediate notifications. Accounts on the legacy experience retain the project **Alerts** page.
## Suggestions
Suggestions are evidence-backed recommendations generated from the current state of your project.
Each suggestion can include context from:
* AI Search prompt and citation performance
* Competitor movement
* Community Discourse overlaps
* Owned-content gaps or changes
* Adoption or AI Demand context where relevant
For each suggestion, you can:
* **Generate brief** to create a fuller execution plan
* **Add to backlog** to commit the work
* **Use existing asset** when you already have a page that should satisfy the recommendation
* **Snooze** when the idea is valid but not timely
* **Dismiss** when it is not a fit
## Briefs
Generating a brief creates a reusable execution artifact for the action. The brief is designed to answer:
* What should we make or update?
* Why does it matter?
* What evidence supports it?
* Which existing assets or external pages matter?
Brief generation spends from your account's single credit balance, which the monthly plan allowance and any purchased packs both fund. Spending takes the expiring allowance first. See **[Account & Billing Overview](/account-billing/overview)** for the full credit policy.
DevTune may automatically prewarm briefs for high-priority suggestions so they are ready faster, but automatic prewarming draws on a capped portion of the monthly allowance rather than the whole balance. If a ready brief becomes stale, the existing markdown stays visible until you choose to regenerate it.
When project content preferences are enabled, Actions and briefs also respect the project's allowed and blocked content formats. Teams can use this to avoid formats that do not fit their strategy, such as comparison pages, while still letting DevTune choose the best allowed format for each recommendation.
## Backlog
Backlog contains work your team has chosen to do. This includes:
* Suggestions adopted from the feed
* Manual actions created directly by your team
Backlog items move through a simple execution workflow:
* **Backlog**
* **In Progress**
* **Blocked**
* **Done**
* **Canceled**
Generated actions keep their detail rail in backlog, so you can still review the summary, evidence, and brief after adopting them.
## Outcomes stage
Outcomes help you review what has been completed and what effect it had. Use this view to connect executed work to downstream movement in AI Search, Community Discourse, Owned Content, and related signals.
When you complete an Action, DevTune creates an **intervention** that monitors the target URL for citation changes. The system tracks whether your content changes resulted in increased AI citations, validating which Actions actually moved the needle.
## How recommendations become work
The usual workflow is:
1. Review **Suggestions**
2. Generate a brief where more context is needed
3. Move the best items into **Backlog**
4. Execute the work
5. Review completed work in **Outcomes**
## Alerts and notification history
In the 2.0 project experience, **Outcomes → Timeline** shows project events and measured changes. Accounts on the legacy experience can still use the project **Alerts** page for notification history.
Account-level notification settings control which events interrupt you immediately and which ones stay in scheduled digests.
## Accessing the workspace
Inside a project sidebar:
* **Actions** opens the actions workspace
* **Outcomes** opens the measured-actions stage
* **Outcomes → Timeline** opens project event history in the 2.0 experience
* **Alerts** opens project event history in the legacy experience
Within **Actions**, you will see:
* **Suggestions**
* **Backlog**
## Getting Started
1. **[Review the Actions workspace](/insights-actions/actions-hub)** - See how suggestions, briefs, and backlog work together
2. **[Configure alerts and digests](/insights-actions/alerts)** - Decide what should interrupt you
3. **[Explore analytics](/analytics/overview)** - Validate the evidence behind a recommendation
## Next Steps
* **[Working with Actions](/insights-actions/actions-hub)** - Review suggestions, backlog, and the Outcomes handoff
* **[Alerts](/insights-actions/alerts)** - Set up notifications and digests
* **[Analytics](/analytics/overview)** - Investigate the data behind a recommendation
# Slack Agent Conversations
Source: https://docs.devtune.ai/integrations/slack-agent-channels
Connect a Slack workspace, link member identities, chat with Dex in threads, and confirm specialist agent runs.
Slack agent conversations are in beta. The **Channels** settings page appears
only for accounts with access to the beta.
Connect DevTune to Slack to ask Dex about a project from a direct message or a
channel thread. Dex can answer follow-up questions in the same thread and can
propose a full run by one of your built-in or custom agents.
## Before you connect
* The person connecting Slack needs permission to manage the DevTune account's
settings.
* Each Slack workspace can connect to only one DevTune account.
* One DevTune account can connect to multiple Slack workspaces.
* Every person using the app must link their own Slack identity to a member of
the connected DevTune account.
* Members still need permission to manage agents and access to the project they
ask Dex to use.
## Connect a Slack workspace
1. Open your DevTune account.
2. Go to **Settings → Channels**.
3. Select **Connect a Slack workspace**.
4. Choose the workspace in Slack and approve the requested access.
5. Return to DevTune. The workspace appears under **Slack workspaces** when the
connection succeeds.
If Slack says the workspace is already connected to another account, disconnect
it from that account before trying again.
## Link your Slack identity
The workspace connection does not give every Slack user access automatically.
DevTune checks each message against a linked DevTune member and applies that
member's existing account and project permissions.
To link yourself:
1. Send the DevTune app a direct message, or mention `@DevTune` in a channel.
2. Open the single-use link that DevTune sends you in a direct message.
3. Sign in to DevTune if prompted. Use a member account that belongs to the
DevTune account connected to this Slack workspace.
4. After DevTune confirms the link, return to Slack and send your question
again.
A link belongs to one person in one Slack workspace. If you use DevTune from
another connected workspace, link your identity there too.
Linked members appear under **Settings → Channels**. A member can select
**Revoke** beside their own link; an account administrator with settings
permission can revoke any member's link. A link also stops working when the
member leaves the DevTune account. The member can ask the app for a new link the
next time they need access.
## Start a conversation
* In a direct message, ask DevTune your question.
* In a channel, mention `@DevTune` and include your question.
Dex starts the conversation in a Slack thread. If you can access only one
project, DevTune uses it automatically. You can also name one accessible project
in your first message. When the project is ambiguous, Dex asks you to choose it
in the thread before answering; your original question is preserved.
After the conversation starts, reply in the same thread. You do not need to
mention the app again. A reply in an unrelated thread does not start a new
conversation: send a direct message or a new `@DevTune` mention instead.
Regular Dex conversation turns begin immediately and consume credits according
to their measured model usage. They do not show an estimate or require a start
confirmation.
## Run a specialist agent
Dex can propose a full run by an available built-in or custom agent when the
request calls for deeper work.
1. Ask Dex for the work you need, or ask it which agents are available.
2. When Dex proposes a specialist run, review the agent, project, and credit
estimate status in the thread.
3. Select **Start run** to confirm. Nothing is queued before the requesting
member confirms.
4. Follow the status messages in Slack, then use the DevTune link to review the
complete result.
Only the member who requested the run can use its confirmation controls. DevTune
checks that member's current permissions and the account's credit balance again
when **Start run** is selected. A proposal can expire or be replaced by a newer
one; start again from Dex when Slack marks it as no longer available.
When that agent and model have positive measured run history, the confirmation
shows an **Estimated per run** credit amount. Without that history, it shows
**No measured runs for this agent yet. The first completed run will provide an
estimate.** No credit amount appears in that case.
The specialist run does not replace Dex in the conversation thread. Dex remains
available for chat while the specialist works. Draft approval and any action
that changes your workflow stay in DevTune during the beta.
## How thread replies work
A Slack thread is connected to one Dex task at a time:
* When Dex is waiting for your reply, your next message goes directly to the
waiting conversation. This includes answers to a question Dex asked.
* When Dex is still working, your reply is queued in order and delivered the
next time the conversation is ready for input.
* An eyes reaction means your message has reached the agent. A queued message
receives the reaction when it is actually delivered. This acknowledgment is
best effort, so a missing reaction does not by itself mean the message failed.
* Started, progress, input-needed, ready, and failure updates appear in the
thread. If Slack cannot receive an update, DevTune keeps the corresponding
update available in the app.
### Inactive conversations
A conversation expires after 30 minutes without a member message while Dex is
waiting. DevTune stops and settles that task and posts an expiry note.
Reply in the same thread to continue. DevTune starts a fresh task with a short
summary of the earlier conversation and posts **Picking this back up**. Because
this is a new task, its usage is recorded separately in the account's credit
transactions.
## Disconnect Slack
To disconnect from DevTune:
1. Go to **Settings → Channels**.
2. Find the workspace under **Slack workspaces**.
3. Select **Disconnect**.
Disconnecting removes DevTune's workspace connection and stored credentials, so
the app can no longer receive messages or post updates for that workspace.
DevTune also stops and settles tasks behind active Slack conversations before
closing those conversations. A Slack workspace administrator should then remove
the DevTune app in Slack; disconnecting in DevTune does not uninstall the app
from Slack. Any result that can no longer be delivered to Slack remains
available in DevTune.
If an administrator removes the app in Slack first, DevTune revokes the
workspace connection and ends active conversations automatically. Since Slack
has already revoked the app's access, those threads may not receive a final
notice. Run history and settled credit activity remain available in DevTune.
## Troubleshooting
### The Channels page is missing
Slack agent conversations are a beta feature. Ask your DevTune contact to
confirm that the beta is available for your account.
### The link does not work
Identity links are single use. Send the app another direct message or mention
to receive a fresh link, then sign in with a member of the connected account.
### Dex asks for a project
Choose one of the projects shown in the thread. DevTune asks only when your
first message does not identify exactly one project you can access.
### A message did not start a conversation
Start from a direct message or a new `@DevTune` mention. Plain messages outside
an active DevTune thread are ignored.
### A run did not start after Dex proposed it
The specialist run begins only after the requesting member selects **Start
run**. If the proposal expired, was replaced, permissions changed, or the
account lacks enough credits, ask Dex to prepare a new proposal after correcting
the issue.
## Next steps
* [Use DevTune agents](/agents/overview)
* [Choose models and understand credits](/agents/models-and-credits)
* [Review credit transactions](/account-billing/credit-transactions)
# Introduction to DevTune
Source: https://docs.devtune.ai/introduction
Track AI Search visibility, community discourse, owned content, AI demand, and recommended actions across modern discovery channels in one DevTune workspace.
Welcome to DevTune. This guide gets you from a blank workspace to a working project that tracks your AI search visibility, community discourse, owned content, AI demand, and recommended actions.
## What is DevTune?
DevTune is a workspace for understanding how your product shows up across modern discovery channels:
* **AI Search** tracks how platforms like ChatGPT, Perplexity, Gemini, Google AI Mode, and Microsoft Bing Copilot cite and describe your brand
* **Community Discourse** monitors relevant discussions across developer communities such as Reddit, GitHub, Hacker News, Dev.to, and Stack Overflow
* **Owned Content** shows what AI crawlers actually extracted from your site and how your content changes between crawls
* **AI Demand** shows what AI systems retrieve and cite, plus the visible referral tail
* **Actions** turns those signals into suggested work, reusable briefs, and backlog items
* **Outcomes** measures completed work and connects it to downstream impact
## Quick Start Path
Follow these steps to get started:
1. **Create Your Account** - Sign up and set up your workspace
2. **Understand Key Concepts** - Learn how projects, brands, prompts, citations, and content credits work
3. **Create Your First Project** - Walk through the onboarding wizard to set up your product, competitors, prompts, and initial run
4. **Explore the Workspace** - Learn how to move between AI Search, Community Discourse, Owned Content, AI Demand, and Actions
> **Note:** DevTune may be operating in waitlist mode. If so, you can join the waitlist from the sign-up page and you will be notified when your account is ready.
## What You'll Learn
In this section, you'll learn how to:
* Create and configure your DevTune account
* Understand the core objects that power DevTune
* Set up your first project using the 5-step onboarding wizard
* Navigate the project workspace and interpret the main signals
Let's get started!
# Working with Projects
Source: https://docs.devtune.ai/projects/overview
Organize and manage DevTune projects: each project tracks one product with its own AI Search, community discourse, owned content, AI demand, and actions.
Projects are the foundation of DevTune. Each project is a dedicated workspace for one product or brand, with its own AI Search tracking, community signals, owned content inventory, AI demand evidence, and action workflow.
> **DevTune 2.0:** The standalone Adoption dashboard is retired, and project event history lives in **Outcomes → Timeline** instead of the legacy Alerts and GTM What Changed pages. Accounts on the legacy experience retain those surfaces.
## What is a Project?
A project in DevTune contains everything related to tracking one product:
* **AI Search** - Prompt-based tracking across supported AI platforms
* **Brands, tracked URLs, and brand terms** - The assets used to match citations and mentions
* **Actions** - Suggestions, briefs, and backlog work
* **Outcomes** - Completed work and measured impact
* **Community Discourse** - Relevant threads, overlaps, and brand presence across community channels
* **Owned Content** - Crawled pages, content diffs, and page-level traffic context
* **Adoption Metrics** - Legacy package download and repository trend tracking
* **AI Demand** - What AI systems retrieve and cite, plus the visible referral tail
## Plan Entitlements
Project features are gated by your subscription plan:
* **Starter** - 25 prompts, 3 AI Search platforms, 5 Community Discourse channels, 10 monthly content credits
* **Plus** - 50 prompts, the same 3 AI Search platforms, API access, 20 monthly content credits
* **Pro** - 100 prompts, all 5 AI Search platforms, AI Demand, 50 monthly content credits
* **Enterprise** - 300 prompts, all platforms, Reddit comments in Community Discourse, project add-ons, per-project monthly content credits, and advanced support
## When to Create Multiple Projects
### One Project Per Product
We recommend creating separate projects for distinct products:
**Good approach:**
* "Payment API" - for your payment processing product
* "Auth Platform" - for your authentication product
* "Analytics Dashboard" - for your analytics product
**Avoid:**
* "All Our Products" - mixing multiple products in one project
### Why Separate Projects?
* **Cleaner metrics** - Each product gets focused visibility scores
* **Focused recommendations** - Suggestions are specific to each product
* **Better organization** - Easy to find what you need
* **Targeted prompts** - Search queries specific to each product
## Project Ownership
Projects belong to **team accounts**, not personal accounts. This means:
* All team members can access shared projects
* Settings and configurations are shared
* Departing team members do not take projects with them
## Creating a New Project
To create a new project:
1. Go to your team's account home page
2. Click **Create Project**
3. Follow the 5-step project setup wizard:
* **Step 1: Product Basics** - Enter your product name, description, and category details
* **Step 2: Review AI-Generated Context** - Review and refine the generated product context
* **Step 3: Add Competitors** - Choose competitor brands to track alongside your primary brand
* **Step 4: Select Prompts** - Choose the AI Search prompts you want to track
* **Step 5: Run Test** - Execute the initial run that populates your baseline results
### Resuming an Incomplete Wizard
If you exit the project creation wizard before completing all steps, your project is saved as a draft. You can resume the wizard at any time by clicking the draft project card on your account home page.
## Managing Multiple Projects
If you have several projects:
* The account home page shows all projects as cards with key statistics
* Use the **search bar** to find projects by name
* Each project card shows recent activity and configuration state
* Click any project card to navigate into it
## Project Lifecycle
### Active Projects
Active projects are the ones you are currently monitoring. Keep your brands, tracked URLs, prompts, and enabled platforms current, and review Actions and **Outcomes → Timeline** regularly. Accounts on the legacy experience can continue reviewing the project Alerts page.
### Deleting Projects
Project deletion is permanent and removes all:
* AI Search data and history
* Adoption Metrics data
* Community Discourse data
* Owned-content history
* AI demand data
* Actions, outcomes, and configurations
To delete a project, use the context menu on the project card on the account home page and select **Delete Project**.
> **Warning:** Deleted projects cannot be recovered.
## Next Steps
* **[Project Settings](/projects/project-settings)** - Edit your project details
* **[Project Navigation](/projects/project-navigation)** - Learn the project interface
* **[Project Members](/projects/project-members)** - Manage team access
# Project Members & Roles
Source: https://docs.devtune.ai/projects/project-members
Manage DevTune project access through team membership, including how shared team-account access works, role permissions, and inviting new members.
DevTune projects are shared within teams. This guide covers how access works, what each role can do, and how to manage your team.
## How Project Access Works
Projects belong to **team accounts**, not individual users. This means:
* Everyone on the team can access all projects in that team
* Access is controlled at the team level, not the project level
* Member permissions apply across all projects in the team
> **Note:** If you need different access for different projects, consider creating separate team accounts for different groups.
## Team Roles
DevTune has two role levels:
### Owner
The team **Owner** has full control:
* Create and delete projects
* Manage billing and subscriptions
* Invite and remove team members
* Change member roles
* Access all settings
* View all results and analytics
Each team has one primary owner. Ownership can be transferred to another team member if needed.
### Member
**Members** have broad access to use DevTune features:
* View all projects
* View results and analytics
* Manage project settings (settings.manage permission)
* Invite new team members (invites.manage permission)
* Create and edit configurations
Members cannot:
* Manage billing
* Remove other team members
* Change member roles
* Delete the team account
## Role Permissions Summary
| Permission | Owner | Member |
| --------------------------------- | ----- | ------ |
| View projects | Yes | Yes |
| View results and analytics | Yes | Yes |
| Manage settings (settings.manage) | Yes | Yes |
| Invite members (invites.manage) | Yes | Yes |
| Manage roles (roles.manage) | Yes | No |
| Manage billing (billing.manage) | Yes | No |
| Remove members (members.manage) | Yes | No |
| Delete team | Yes | No |
| Transfer ownership | Yes | No |
## Managing Team Members
### Viewing Current Members
To see who is on your team:
1. Go to your team account page
2. Navigate to the **Members** tab
3. View all current members and their roles
### Inviting New Members
Both Owners and Members can invite new people to the team:
1. Go to the team page and select the **Members** tab
2. Click **Invite Member**
3. Enter their email address
4. Select a role -- Owners see a role dropdown and can assign either Owner or Member; Members can only invite as Member (no role selection shown)
5. Send the invitation
The invitee receives an email with instructions to join. There is a limit of **5 pending invitations** at a time. Invitations expire after a set period.
### Auto-Join by Domain
Owners can configure a domain for automatic team joining:
1. Go to team settings
2. Set the **Auto-Join Domain** (e.g., "acme.com")
3. Users who sign up with an email address matching that domain are automatically added to the team
This is useful for organizations where all employees share a common email domain.
### Changing Member Roles
To change someone's role (Owner only):
1. Go to the Members tab
2. Find the member in the list
3. Click the role dropdown
4. Select the new role
5. Confirm the change
> **Note:** Only Owners can change roles. You cannot change your own role or assign a role higher than your own.
### Removing Members
To remove someone from the team (Owner only):
1. Go to the Members tab
2. Find the member to remove
3. Click the remove option
4. Confirm the removal
Removed members:
* Immediately lose access to all projects
* Cannot see any team data
* Must be re-invited to regain access
## Leaving a Team
If you want to leave a team yourself:
1. Go to the team settings
2. Find the **Leave Team** option
3. Confirm your departure
> **Note:** The primary Owner cannot leave without transferring ownership first.
## Multiple Teams
You can be a member of multiple teams:
* Each team has its own projects
* Switch between teams using the team selector in the header
* Your role may be different in each team
## Best Practices
### Role Assignment
* **Owners** - Typically the team lead or billing contact
* **Members** - Day-to-day users who work with projects and results
### Onboarding New Members
When adding new team members:
1. Invite them with the appropriate role
2. Point them to the project documentation
3. Walk them through your project structure
4. Explain your tracking workflows
### Offboarding Members
When someone leaves:
1. Remove them from the team promptly (Owner action)
2. Review any configurations they created
3. Update any shared credentials if applicable
## Next Steps
* **[Team Management](/account-billing/team-management)** - More details on team administration
* **[Account Settings](/account-billing/account-settings)** - Configure your personal account
# Navigating Your Project
Source: https://docs.devtune.ai/projects/project-navigation
Understand the DevTune project sidebar layout, including the Overview, AI Search, community, owned content, AI Demand, and Project Settings sections.
Once inside a project, you will find a sidebar that gives you access to all of DevTune's major surfaces. This guide explains how the workspace is organized and what each route is for.
> **DevTune 2.0:** The sidebar follows the Visibility → Traffic → Act → Outcomes loop. Adoption is retired, while legacy Alerts and Timeline routes open **Outcomes → Timeline**. Accounts on the legacy experience retain the older entries described below.
## Sidebar Structure
The project sidebar is organized into three main sections.
### Overview
The Overview section is where work gets reviewed and prioritized.
* **Actions** - Suggestions, generated briefs, and backlog work
* **Outcomes** - Completed work, measured impact, attribution, and timeline evidence; the Timeline tab owns project event history in the 2.0 experience
* **Alerts** - Legacy project event history, regressions, competitor threats, and digest-style updates
* **Timeline** - Legacy shared chronology for community activity, content changes, annotations, and downstream outcomes
### Signals
This section is where your product signals are measured.
* **AI Search** - The core visibility workspace with tabs for **Dashboard**, **Prompts**, **Citations**, **Competitors**, and **Analytics**
* **Adoption Metrics** - Legacy package and repository adoption trends tied to your product and tracked competitors
* **Community Discourse** - Threads, replies, source overlaps, brand share, intent mix, and community citations across developer communities
* **Owned Content** - Content Explorer for your crawled site tree, content history, and page-level AI traffic context
* **AI Demand** - What AI systems retrieve and cite, plus the visible referral tail
### Settings
The project-level configuration page is centralized under **Project Settings**. It includes:
* **General** - Project name, description, and product context
* **Brands** - Brand list plus a detail panel for tracked URLs and brand terms
* **Platforms** - AI Search platform toggles based on your plan
* **Content Preferences** - Format allowlists, blocklists, and style notes when enabled for your account
* **AI Traffic** - Tracking snippet generation and collection controls
The **Brands** tab replaces the older split between separate tracked-URL and brand-term tabs.
## Entitlement Gating
Some project sidebar sections and account-level tools may be hidden or locked based on your subscription plan:
* **Starter / Plus** - ChatGPT, Perplexity, and Gemini in AI Search; Community Discourse threads; no AI Demand
* **Pro and above** - Google AI Mode, Microsoft Bing Copilot, and AI Demand
* **Enterprise** - Reddit comments in Community Discourse
* **Plus and above (account level)** - API keys, webhooks, and the MCP server
If a section is not visible, it may require a plan upgrade. Check your team's billing settings to see available plans.
## Quick Navigation Tips
### Breadcrumbs
Look for breadcrumbs at the top of pages to understand where you are in the navigation hierarchy and navigate back to parent pages.
### Project Switcher
Use the project dropdown in the header to switch between projects without returning to the account home page.
### Account Home
Click the team name in the header to return to the account home page where all projects are listed.
## Next Steps
* **[Project Members](/projects/project-members)** - Manage team access
* **[Set Up AI Search](/search-tracking/getting-started)** - Configure visibility monitoring
* **[Open Actions](/insights-actions/actions-hub)** - Review AI-generated recommendations
# Project Settings
Source: https://docs.devtune.ai/projects/project-settings
Use the centralized Project Settings page to manage your project's general setup, brands, AI Search platforms, content preferences, and AI Traffic configuration.
Project Settings is the centralized configuration page for each project. It replaces the older mix of modal editing and separate configuration tabs with one place to manage project context, brands, platforms, content preferences, and AI Traffic.
## Accessing Project Settings
Open your project, then use the sidebar:
1. Go to **Project Settings**
2. Choose the tab you want to work in
The page includes these tabs:
* **General**
* **Brands**
* **Platforms**
* **Content Preferences** when enabled for your account
* **AI Traffic**
## General Tab
Use the **General** tab to edit the core project record:
* **Project name**
* **Description**
* **Product context**
The product context is the structured description DevTune uses to interpret prompts, competitor relevance, and recommended actions. If your product positioning changes, update this tab first.
## Brands Tab
The **Brands** tab is the operational heart of project setup. It combines what used to be managed across separate tracked-URL and brand-term tabs.
### What the Brands tab includes
* A left-hand brand list with your primary brand and tracked competitors
* A right-hand detail panel for the selected brand
* Suggested competitor imports where available
### What you manage per brand
Inside the brand detail panel you manage:
* **Tracked URLs / citation sources** - The domains and URLs DevTune should match in AI Search responses
* **Brand terms** - The text terms DevTune should treat as direct brand mentions
* **Brand metadata** - Primary versus competitor classification and brand identity
This is where you keep your primary brand, competitor brands, tracked URLs, and brand-term coverage aligned.
## Platforms Tab
The **Platforms** tab controls which AI Search platforms DevTune queries for this project.
Supported platforms are:
* ChatGPT
* Perplexity
* Gemini
* Google AI Mode
* Microsoft Bing Copilot
Not every platform is available on every plan. Locked platforms show upgrade messaging instead of an enabled toggle.
Turning a platform off stops future runs from querying it, but it does not remove historical data that was already collected.
## Content Preferences Tab
The **Content Preferences** tab controls which content formats DevTune may recommend when it creates Actions and generates briefs for this project.
Content preferences are account-feature gated during beta. If the tab is not visible, DevTune uses the default behavior: all content formats are allowed.
From this tab you can:
* Keep the default **allow all** behavior
* Move formats into a blocklist, such as comparison pages or alternative pages
* Narrow the allowed formats for a project
* Add style notes that guide action and brief generation
These preferences affect both best-fit recommendations and manual brief-style choices. DevTune will not intentionally recommend a blocked format. If a requested brief style is blocked, brief generation rejects that request instead of silently using it.
## AI Traffic Tab
The **AI Traffic** tab is where you configure the website snippet used for AI bot and referral analytics.
From this tab you can:
* Generate the project-specific tracking snippet
* Copy the snippet for installation on your site
* Enable or disable collection
* Confirm the snippet key currently attached to the project
Projects without AI Traffic configured show an empty state with a setup action. AI Traffic requires a plan that includes that feature.
## Editing Versus Deleting
Use Project Settings for ongoing configuration. If you need to delete a project entirely, that is still handled from the project card menu on the account home page.
> **Warning:** Project deletion is permanent and removes the project's AI Search data, Community Discourse data, owned-content history, AI Traffic data, actions, and configuration.
## Best Practices
* Keep the **General** tab current whenever your positioning or core features change
* Review the **Brands** tab whenever you launch new docs, blogs, or package pages
* Revisit **Platforms** when you upgrade plans or want to narrow scope
* Use **Content Preferences** when your team has clear format rules, such as avoiding comparison pages or preferring technical guides
* Treat the **AI Traffic** tab as part of your production instrumentation checklist
## Next Steps
* **[Project Navigation](/projects/project-navigation)** - Learn the project interface
* **[Project Members](/projects/project-members)** - Manage team access
* **[AI Search Setup](/search-tracking/getting-started)** - Configure your tracking
# AI Search Citations
Source: https://docs.devtune.ai/search-tracking/citations
Track which URLs ChatGPT, Perplexity, Gemini, and other AI platforms cite, with first-party vs third-party classification, domain ranking, and detail pages.
Citations track the specific URLs that AI platforms reference in their responses. While tracked URLs tell DevTune what to look for, the Citations page shows you exactly which URLs were cited, how often, and on which platforms.
## What are Citations?
When AI assistants respond to prompts, they often reference specific URLs as sources:
> "According to the documentation at docs.example.com/getting-started..."
or
> "Sources: \[1] docs.example.com/api-reference \[2] competitor.com/docs..."
Citations are these specific URL references. DevTune captures every cited URL and classifies it based on your configured tracked URLs and brands.
## Why Citations Matter
### Direct Traffic Potential
Cited URLs are clickable links in most AI platforms. Users may visit cited sources to learn more, making citations a direct traffic driver.
### Authority Signal
Being cited by AI platforms indicates that your content is recognized as authoritative. Frequent citations validate your content quality and relevance.
### Content Performance Indicator
Citations show which specific pages in your site are performing well in AI search. This data directly guides content strategy decisions.
## Citation Classification
DevTune classifies every citation into one of three categories:
### Primary Citations
URLs that match tracked URLs belonging to your primary brand. These are your own domains being cited.
**Example:** `docs.yourcompany.com/getting-started` matches your primary brand tracked URL `docs.yourcompany.com`.
### Competitor Citations
URLs that match tracked URLs belonging to a competitor brand. These show competitor content being cited alongside (or instead of) yours.
**Example:** `docs.competitor.com/api-reference` matches a competitor brand tracked URL.
### Other Citations
URLs that do not match any configured tracked URL. These are third-party sources like Stack Overflow, Wikipedia, blog posts from unrelated sites, and other external pages.
Other citations provide context about the broader information landscape AI platforms draw from for your tracked prompts.
## Citation Stats Overview
At the top of the Citations page, summary statistics provide a quick overview:
* **Total Citations** - The total number of citation instances across all prompts and platforms
* **Unique Domains** - The number of distinct domains cited across all results
* **Primary Citation Share** - The percentage of total citations that point to your primary brand domains
Primary Citation Share is a key competitive metric. A high Primary Citation Share means AI platforms preferentially cite your content over competitors and other sources.
Overall Presence Rate uses these same tracked-URL matches with a response denominator: a completed response contributes once when it cites at least one URL tracked to your brand. Uncited brand-name text is reported separately as Brand Mentions.
## Domain Ranking
The Citations page includes a domain ranking view that shows the most-cited domains across all your tracked prompts.
### Ranking Features
* Domains are ranked by total citation count
* Domain logos are displayed where available for visual identification
* Each domain shows its classification (primary, competitor, or other)
* Citation count and percentage share are displayed per domain
### Using Domain Rankings
Domain rankings help you understand:
* Which competitor domains are cited most frequently
* Whether your documentation or blog or marketing site gets cited more
* Which third-party sources AI platforms trust in your category
* How your citation count compares to competitors
## Viewing Citation Details
### Citations List
The main Citations page shows all cited URLs with:
* The full URL
* Citation count (how many times it was cited)
* The brand classification (primary, competitor, other)
* Which platforms cited it
* Which prompts triggered the citation
### Per-Citation Detail Page
Click any citation to see its detail page, which includes:
* The full URL and page title (if available)
* Total citation count across all test runs
* Platform breakdown showing which AI platforms cite this URL
* Prompt breakdown showing which prompts produce this citation
* Historical trend of citation frequency
* Sample response excerpts where the URL was cited
## Platform Citation Behavior
Different AI platforms have different citation behaviors:
### Perplexity
Perplexity is citation-heavy. It typically includes multiple source references in every response, making it an important platform for citation tracking.
### ChatGPT
ChatGPT citation behavior varies by query type and response format. Some responses include detailed citations while others do not.
### Google AI Mode
Google AI Mode typically links to source pages from web search results, often with inline references.
### Gemini
Gemini citation behavior varies and may include links to source material depending on the query.
### Microsoft Bing Copilot
Microsoft Bing Copilot may reference sources, particularly for factual or technical queries.
## Improving Your Citations
### Create Citable Content
Content that tends to get cited by AI platforms:
* Comprehensive documentation with clear structure
* Authoritative, well-researched writing
* Unique data, benchmarks, or insights
* Clear answers to specific questions
* Up-to-date, accurate information
### Page Structure
Help AI platforms identify and cite your content:
* Use clear headings that match common query patterns
* Write concise, quotable paragraphs
* Make definitive statements that AI can reference
* Keep information current and accurate
### Content Breadth
Cover the topics your audience asks about:
* Getting started guides
* API references
* Tutorial and how-to content
* Comparison pages
* Troubleshooting guides
## Citation Entitlements
Citation tracking features may vary by plan tier. Some detail views and historical depth may require higher-tier plans. Check your plan details for specific citation tracking entitlements.
## Working with Citation Data
### Content Strategy
Use citation data to guide your content investment:
**Well-cited pages:**
* Maintain and keep up to date
* Use as templates for new content
* Expand into related topics
**Pages not being cited:**
* Review content quality and relevance
* Check whether the page addresses common prompts
* Consider restructuring or improving the content
### Competitive Analysis
Use competitor citation data to:
* Identify competitor content that AI platforms prefer
* Understand what makes competitor content citable
* Find gaps where you can create superior content
## Next Steps
* **[Tracked URLs](/search-tracking/domains)** - Manage the URLs DevTune attributes to brands
* **[Prompts](/search-tracking/prompts)** - Manage queries that generate citations
* **[Understanding Metrics](/search-tracking/visibility-metrics)** - How citations feed into metrics
* **[Platform Comparison](/search-tracking/platform-comparison)** - Compare citation behavior across platforms
# AI Search Competitors
Source: https://docs.devtune.ai/search-tracking/competitors
See which competing brands win AI Search citations, the topics they lead on, and where your brand is missing using the Brand Citation Landscape view.
The **Competitors** tab is the competitive lens inside AI Search. It turns the raw citation set into a topic-by-topic view of which brands are being cited most, how they compare to your primary brand, and where competitor pressure is strongest.
## What the Competitors Tab Shows
The page combines a shared filter bar with two main visuals:
### Brand Citation Landscape
This view summarizes which brands are winning citations in the selected date range. It is designed to answer:
* Which competitor brands show up most often?
* Are we getting cited as often as the leaders?
* How concentrated is citation volume across a few brands?
### Topic List
The topic panel lets you narrow the competitive view to one topic at a time. This makes it easier to see whether a competitor is broadly strong or only dominating a specific query cluster.
### Competitor Presence Matrix
Below the citation landscape, DevTune renders a topic-by-brand matrix that shows which brands are showing up across the tracked topic set. Use it to spot:
* Topics where you are consistently absent
* Topics where one competitor is dominating
* Areas where multiple brands are tightly clustered
## Filters
The Competitors tab follows the shared AI Search / GTM-style filters for:
* **Source**
* **Platform**
* **Date range**
Use these to answer more precise questions, such as:
* Who wins on Perplexity specifically?
* Which competitor leads on docs-heavy citations?
* Did a competitor surge in the last 30 days?
## How to Use It
A practical workflow is:
1. Start with the overall citation landscape to see the top competitive brands
2. Click through topics to isolate where the pressure is strongest
3. Use the presence matrix to confirm whether a gap is isolated or systemic
4. Open **Actions** or **Community Discourse** to decide whether the right response is docs, content, community work, or a competitive asset
## Best Practices
* Keep competitor brands and tracked URLs current in **Project Settings > Brands**
* Use the **Platform** filter when a competitor appears strong on only one AI Search engine
* Review this tab alongside **Citations** so you can see not just which brand wins, but which exact URLs are doing the work
## Next Steps
* **[Citations](/search-tracking/citations)** - Inspect the exact URLs behind competitive wins
* **[Prompts](/search-tracking/prompts)** - See which prompt clusters drive the competitive gap
* **[Actions Workspace](/insights-actions/actions-hub)** - Turn competitive gaps into prioritized work
# Tracked URLs
Source: https://docs.devtune.ai/search-tracking/domains
Configure the tracked URLs and domains DevTune monitors for citations and links in AI Search responses, managed per brand from Project Settings.
Tracked URLs are the domains and URLs DevTune monitors for appearances in AI Search responses. When an AI platform cites a URL or links to a website in its response, DevTune checks whether that URL belongs to one of your configured brands.
## Where Tracked URLs Are Managed
Tracked URLs are now managed from **Project Settings > Brands**.
Select a brand in the left-hand list, then use the brand detail panel to review and edit that brand's tracked URLs.
## What Counts as a Tracked URL
Typical sources include:
* Marketing site
* Documentation site
* Blog
* GitHub repository
* Package registry pages
Each source is attached to a brand, which lets DevTune distinguish between:
* **Primary citations** - Your brand's URLs
* **Competitor citations** - Competitor URLs
* **Other citations** - URLs that are not assigned to a tracked brand
## Choosing What to Track
For your primary brand, usually track:
* Main product site
* Docs
* Blog
* GitHub
* Package pages
For competitor brands, usually track:
* Their main product site
* Their docs
* Their package / repository footprint
## Why Tracked URLs Matter
Tracked URLs power:
* Presence metrics
* Citation-share metrics
* Competitive comparisons
* Prompt and URL-level analysis
If an important property is missing here, DevTune cannot credit that citation to the correct brand.
## Best Practices
* Track the content properties that actually matter in your buying journey
* Keep primary and competitor URL sets current
* Review this setup whenever you launch a new docs site, move a blog, or add a new package surface
## Troubleshooting
### A page is being cited but not counted correctly
Check whether:
* The relevant domain or URL is assigned to the correct brand
* The property is missing entirely from the brand's tracked URLs
* The cited page lives on a new host you have not added yet
### A competitor seems stronger than expected
Sometimes the competitor set is incomplete or one competitor's strongest URL set is not yet tracked. Review their brand entry and expand its tracked URLs before drawing a conclusion.
## Next Steps
* **[Citations](/search-tracking/citations)** - Inspect the exact URLs getting cited
* **[Brand Terms](/search-tracking/keywords)** - Manage the text terms used for mention matching
* **[AI Search Configuration](/search-tracking/search-configuration)** - Review the current settings structure
# Setting Up AI Search
Source: https://docs.devtune.ai/search-tracking/getting-started
Configure brands, tracked URLs, brand terms, prompts, and platforms in DevTune to start running prompt-based AI Search visibility tracking on your project.
This guide walks you through the current AI Search setup flow. By the end, you will have the project objects DevTune needs to run prompt-based AI Search tracking and interpret the results correctly.
## Before You Start
You will need:
* A DevTune project created through the onboarding wizard
* An understanding of which brands and URLs represent you and your competitors
* A first pass at the prompts you want to track
If you completed the onboarding wizard, much of this is already pre-populated. This guide covers how to review and refine it.
## Where Setup Happens
AI Search setup now spans two places:
* **Project Settings** - General, Brands, Platforms, and AI Traffic
* **AI Search > Prompts** - Prompt and topic management
The biggest structural change is that tracked URLs and brand terms are now managed inside the **Brands** tab rather than separate top-level config tabs.
## Step 1: Review the General tab
Open **Project Settings > General** and confirm:
* Project name
* Description
* Product context
If the product context is wrong or outdated, fix it before tuning anything else. It influences how DevTune evaluates relevance and generates recommendations.
## Step 2: Configure Brands, tracked URLs, and brand terms
Open **Project Settings > Brands**.
This tab shows:
* A brand list on the left
* A detail panel for the selected brand on the right
### Primary brand
Your primary brand is created during setup and represents your product. It defines which citations and mentions count as "yours."
### Competitor brands
Add competitor brands you want to track alongside your own. DevTune can also suggest competitors based on project context.
### Tracked URLs
Within a brand's detail panel, add the domains or URLs DevTune should match as citations, such as:
* Marketing site
* Docs
* Blog
* GitHub repository
* Package registry pages
### Brand terms
Also within the same detail panel, add the text terms that should count as brand mentions, such as:
* Official product name
* Common variations
* Common abbreviations
## Step 3: Enable AI Search platforms
Open **Project Settings > Platforms** and enable the AI Search engines you want DevTune to query.
Platform availability depends on your plan:
* **Starter / Plus** - ChatGPT, Perplexity, Gemini
* **Pro / Agency / Enterprise** - ChatGPT, Perplexity, Gemini, Google AI Mode, Microsoft Bing Copilot
Disabling a platform stops future runs on that engine but does not remove historical data already collected.
## Step 4: Manage prompts and topics
Open **AI Search > Prompts** to review the queries DevTune is sending.
From this tab you can:
* Add or edit prompts
* Group prompts into topics
* Review prompt-level performance
* Use blue-ocean and red-ocean analysis to prioritize coverage
Prompts define the actual questions DevTune submits to the enabled AI platforms, so they are one of the highest-leverage parts of the setup.
## Step 5: Let runs accumulate
Once brands, tracked URLs, terms, prompts, and platforms are configured, DevTune runs AI Search tracking on its managed schedule. As runs complete, you will see data appear in:
* **Dashboard**
* **Prompts**
* **Citations**
* **Competitors**
* **Analytics**
## Optional: Configure AI Traffic
If your plan includes AI Traffic, you can also open **Project Settings > AI Traffic** and generate the website snippet that tracks AI bot visits and AI referrals. This is not required for AI Search itself, but it gives you downstream traffic context.
## After Setup
### Establish a baseline
Your first completed runs establish the baseline for:
* Presence
* Share of Voice
* Brand mentions
* Citation coverage
### Expect some variability
AI Search results are not perfectly deterministic. Focus on patterns across multiple runs rather than any single response.
## Troubleshooting
### No results appearing
If you do not see results:
* Confirm that at least one platform is enabled
* Confirm you have prompts configured
* Confirm your brands, tracked URLs, and brand terms are present
* Give the scheduled runs time to complete
### Unexpected results
If results seem off:
* Review tracked URLs for typos or missing properties
* Review brand terms for missing or overly broad matches
* Confirm you are looking at the correct platform/date filters
## Next Steps
* **[Search Configuration](/search-tracking/search-configuration)** - Review the current settings structure
* **[Prompts](/search-tracking/prompts)** - Manage tracked queries
* **[Search Dashboard](/search-tracking/search-overview-dashboard)** - Understand your baseline
* **[Visibility Metrics](/search-tracking/visibility-metrics)** - Learn how the KPIs are calculated
# Brand Terms
Source: https://docs.devtune.ai/search-tracking/keywords
Manage the brand-name terms DevTune uses to detect and classify your product or competitor mentions in AI Search responses, configured per brand.
Brand terms are the text terms DevTune monitors for brand mentions in AI Search responses. When a platform names your product or a competitor directly in response text, DevTune uses brand terms to classify that mention.
## Where Brand Terms Are Managed
Brand terms are now managed from **Project Settings > Brands**.
Select a brand in the left-hand list, then use the brand detail panel to review and edit the terms for that brand.
## What Brand Terms Do
Brand terms answer a different question from tracked URLs:
* **Tracked URLs** tell DevTune which cited links belong to a brand
* **Brand terms** tell DevTune which response-text mentions belong to a brand
That means DevTune can still detect a brand mention even when the response names the product without citing one of its URLs.
## What to Add
For each brand, add:
* Official product name
* Common spacing or casing variations
* Widely used abbreviations
* Any common alternative spelling that appears in real-world discussion
## What Not to Add
Avoid overly generic terms that would produce false positives, such as:
* Category names
* Generic technical phrases
* Short ambiguous acronyms unless they are genuinely distinctive in your space
## Why Brand Terms Matter
Brand terms feed:
* Brand Mention Rate
* Share of Voice
* Competitive prompt analysis
* Prompt-detail response sidebars and highlights
If a brand is clearly being named in responses but not showing up in analysis, missing or weak brand-term coverage is often the cause.
## Best Practices
* Keep the list precise rather than exhaustive
* Add the terms people actually use, not every conceivable variation
* Review the list when you rebrand or start tracking a new competitor
## Troubleshooting
### Mention counts seem too low
Check whether:
* Common variations are missing
* Abbreviations used in real responses were never added
* The term belongs to the wrong brand
### Mention counts seem too high
Check whether:
* The term is too generic
* An abbreviation overlaps heavily with unrelated products or concepts
## Next Steps
* **[Prompts](/search-tracking/prompts)** - Review the prompts that generate those mentions
* **[Tracked URLs](/search-tracking/domains)** - Manage tracked URLs alongside term matching
* **[Visibility Metrics](/search-tracking/visibility-metrics)** - See how brand terms affect the KPIs
# AI Search Overview
Source: https://docs.devtune.ai/search-tracking/overview
Monitor your brand presence, share of voice, and citations across AI-powered search platforms like ChatGPT, Perplexity, Gemini, Google AI Mode, and Microsoft Bing Copilot.
AI Search tracks how visible your product is when users ask AI platforms about your category, problems, or competitors. It is the core DevTune surface for measuring whether AI platforms mention your brand, cite your content, and recommend you relative to the alternatives your buyers are considering.
## What AI Search Answers
AI Search helps you answer questions like:
* Do ChatGPT, Perplexity, Gemini, Google AI Mode, and Microsoft Bing Copilot mention us?
* Which of our pages are actually getting cited?
* Which prompts do competitors win?
* Are we improving over time or losing ground?
## The AI Search Workspace
The AI Search page is organized into five tabs:
* **Dashboard** - KPI cards, trend views, and top-level visibility summaries
* **Prompts** - Prompt management, blue-ocean versus red-ocean analysis, and prompt-level detail
* **Citations** - URL-level citation tracking across brands and domains
* **Competitors** - Competitive citation landscape and topic-by-topic competitor presence
* **Analytics** - Deeper charts and filtered trend analysis
## Supported Platforms
DevTune tracks presence across five major AI Search platforms:
* **ChatGPT**
* **Perplexity**
* **Gemini**
* **Google AI Mode**
* **Microsoft Bing Copilot**
Platform availability depends on your plan:
* **Starter / Plus** - ChatGPT, Perplexity, and Gemini
* **Pro / Agency / Enterprise** - All five platforms
## Core Metrics
The AI Search workspace is built around a few recurring metrics.
### Overall Presence Rate
The percentage of completed AI responses that cite at least one URL tracked to your brand. Each response counts once, even when it cites several of your URLs.
### Share of Voice
Your share of total mentions and citations across the selected prompt set, relative to tracked competitors.
### Sentiment Score
How positively or negatively AI platforms discuss your brand when they mention it.
### Brand Mentions
How often AI platforms name your brand directly in their response text, even when they do not cite one of your URLs.
### Primary Citation Share
The share of citations that point to your tracked URLs rather than competitors or third-party sources.
## What You Configure
AI Search works from a few core project objects:
* **Prompts** - The queries DevTune submits to AI platforms
* **Brands** - Your primary brand and tracked competitors
* **Tracked URLs** - The domains and URLs DevTune should match as citations
* **Brand terms** - The text terms DevTune should match as mentions
* **Platforms** - Which AI Search engines are enabled for the project
These are managed from **Project Settings** and the **Prompts** tab.
## Why AI Search Matters
AI Search is now part of how developers discover tools, compare vendors, and evaluate implementation options. If AI platforms consistently recommend competitors, cite third-party sources instead of your docs, or fail to mention your brand at all, that becomes a real acquisition and perception problem.
The goal is not only to rank in a classic search engine. It is to become the content and product that AI systems choose to reference and recommend.
## Getting Started
1. **[Set Up AI Search](/search-tracking/getting-started)** - Configure brands, tracked URLs, prompts, and platforms
2. **[Configure Tracking](/search-tracking/search-configuration)** - Review the current Project Settings structure
3. **[Review the Dashboard](/search-tracking/search-overview-dashboard)** - Understand your current visibility baseline
4. **[Explore Metrics](/search-tracking/visibility-metrics)** - Learn what each KPI actually means
## Next Steps
* **[AI Search Setup](/search-tracking/getting-started)** - Configure your project
* **[Prompts](/search-tracking/prompts)** - Manage and analyze tracked prompts
* **[Competitors](/search-tracking/competitors)** - Review competitive citation landscape
* **[Analytics](/analytics/search-analytics)** - Explore filtered trend charts
# Platform Comparison
Source: https://docs.devtune.ai/search-tracking/platform-comparison
Compare AI Search visibility across ChatGPT, Perplexity, Gemini, Google AI Mode, and Microsoft Bing Copilot to find platform-specific gaps and decide where to invest content.
Different AI platforms surface your brand differently. Understanding platform-specific performance helps you decide whether you need broad content improvements or platform-specific fixes.
## Why Platforms Differ
Platforms vary because they draw on different data and present answers differently:
* **ChatGPT** mixes model knowledge with live web search
* **Perplexity** is citation-heavy and search-native
* **Gemini** and **Google AI Mode** are shaped by Google's search ecosystem
* **Microsoft Bing Copilot** combines web search with conversational answers
This affects:
* How often platforms mention brands
* How many sources they cite
* Which kinds of pages they prefer to cite
## Platform Availability by Plan
Platform coverage depends on your plan:
| Platform | Starter | Plus | Pro | Agency / Enterprise |
| -------------- | ------- | ---- | --- | ------------------- |
| ChatGPT | Yes | Yes | Yes | Yes |
| Perplexity | Yes | Yes | Yes | Yes |
| Gemini | Yes | Yes | Yes | Yes |
| Google AI Mode | No | No | Yes | Yes |
| Bing Copilot | No | No | Yes | Yes |
## What to Compare
At the platform level, the most useful comparisons are:
* **Presence Rate**
* **Brand Mention Rate**
* **Primary Citation Share**
* **Share of Voice**
These make it easier to spot situations such as:
* Strong overall performance but weak Perplexity citations
* Good citation coverage but weak ChatGPT brand mention rates
* Competitor strength concentrated on only one platform
## How to Use Platform Comparison
### Find platform strengths
Look for platforms where you are already strong:
* High presence
* Strong citation share
* Healthy Share of Voice
These are your current benchmarks.
### Find platform weaknesses
Look for platforms where you underperform:
* Low presence compared to your other platforms
* Low or declining Share of Voice
* Weak citation coverage versus competitors
These are usually the best starting points for deeper prompt or citation analysis.
## Reading the Results
When one platform looks much weaker than the others, ask:
* Are competitors winning the same prompts there?
* Are those responses citing a different class of content?
* Are we being mentioned but not cited, or absent entirely?
Usually the next step is to jump into:
* **Prompts** for prompt-level breakdown
* **Citations** for URL-level detail
* **Competitors** for the competitive landscape
## Next Steps
* **[Prompts](/search-tracking/prompts)** - Inspect prompt-by-platform performance
* **[Citations](/search-tracking/citations)** - Compare citation behavior by platform
* **[Competitors](/search-tracking/competitors)** - Review who wins on the same platform/date slice
# AI Search Prompts
Source: https://docs.devtune.ai/search-tracking/prompts
Manage the prompts DevTune submits to AI platforms each run and inspect prompt-level responses, citations, brand mentions, and competitive context.
Prompts are the search queries DevTune submits to AI platforms during each run. They are the unit that ties the whole AI Search workspace together: metrics, competitor comparisons, citations, and recommendations all begin with prompts.
## What a Prompt Represents
A prompt should look like something a real user would ask an AI assistant, for example:
* "What is the best API testing tool for microservices?"
* "How do I implement rate limiting in Node.js?"
* "Compare authentication libraries for React applications"
DevTune sends each prompt to the enabled AI Search platforms and analyzes the responses for your brands, tracked URLs, citations, and competitor presence.
## The Prompts Tab
The Prompts page combines:
* A topic sidebar
* Prompt management
* Blue-ocean versus red-ocean analysis
* Prompt-level performance views
Use it to understand not just whether you are visible overall, but which specific questions you are winning or losing.
## Prompt Detail
Opening a prompt shows the platform responses and a persistent side panel with the response context DevTune could recover.
Depending on the platform and response, that side panel can include:
* **Mentioned Brands**
* **Citations & Sources**
* **Web Search Queries**
* **Search Sources**
* **X Posts**
This makes it easier to inspect how each platform formed the answer, not just whether you appeared in it.
## Prompt Limits by Plan
Your subscription plan determines how many prompts you can actively track:
| Plan | Prompt Limit |
| ------------------- | ------------ |
| Starter | 25 |
| Plus | 50 |
| Pro | 100 |
| Agency / Enterprise | 300 |
## Blue Ocean and Red Ocean Analysis
DevTune categorizes prompts based on the competitive landscape of the responses.
### Red Ocean
Red-ocean prompts are highly competitive. Multiple brands are showing up, and improvement usually means displacing an existing competitor.
### Blue Ocean
Blue-ocean prompts are lower-competition opportunities where AI Search results are less crowded and new presence is easier to establish.
## Opportunity Thinking
The most valuable prompt work usually comes from:
* Prompts where you are absent but the topic matters
* Prompts where competitors dominate citations
* Prompts where you are already present and can defend that position with better content
## Prompt Strategy
It helps to mix several prompt types:
* **Discovery prompts** - broad category exploration
* **Evaluation prompts** - comparisons and vendor selection
* **Integration prompts** - implementation and onboarding
* **Migration prompts** - switching from competitor tools
* **Troubleshooting prompts** - practical problems and errors
## Best Practices
* Write prompts the way real users ask them
* Cover the feature areas that actually drive your pipeline
* Group related prompts into topics so you can analyze themes, not just individual queries
* Review prompt detail pages when a metric looks surprising
## Next Steps
* **[Topics](/search-tracking/topics)** - Organize prompts by theme
* **[Citations](/search-tracking/citations)** - See which URLs are being cited for those prompts
* **[Competitors](/search-tracking/competitors)** - Understand who wins the same prompt clusters
* **[Visibility Metrics](/search-tracking/visibility-metrics)** - Learn how prompt results feed the KPIs
# Running AI Search Runs
Source: https://docs.devtune.ai/search-tracking/running-search-tests
Understand how DevTune schedules AI Search runs automatically, what each run measures, and how to interpret presence, citation, and brand mention results.
AI Search runs query the enabled platforms with your configured prompts to measure presence, citations, mentions, and competitive position. This guide explains what happens during a run and how to think about the results.
## How Runs Are Scheduled
AI Search runs are scheduled automatically by DevTune. You do not need to manually trigger them or set up your own job schedule.
In practice, once a project is configured, DevTune handles the recurring execution and stores the results for trend analysis.
## What Happens During a Run
Each run follows a consistent flow.
### 1. Query submission
DevTune sends each configured prompt to every enabled AI Search platform.
### 2. Response collection
The platform response is captured, including:
* Main answer text
* Cited URLs and sources where available
* Additional structured response context that the provider exposes
### 3. Analysis
Each response is analyzed against your project configuration:
* Tracked-URL matching
* Brand-term matching
* Competitor presence detection
* Citation/source recovery
* Sentiment and placement analysis
### 4. Metric calculation
From that analysis, DevTune updates:
* Overall Presence Rate
* Share of Voice
* Sentiment Score
* Prompt-level results
* Citation-level results
* Platform-level breakdowns
### 5. Recommendation generation
The resulting signal set can then feed:
* Suggested actions
* Brief generation
* Competitive gap analysis
* Outcome tracking over time
## What Affects Run Scope
Run scope depends mainly on:
* **Number of prompts**
* **Number of enabled platforms**
* **Your current plan**
This is why prompt selection and platform selection matter operationally, not just analytically.
## Viewing Results
After runs complete, the results appear across the AI Search workspace:
* **Dashboard** - Top-level KPI and trend context
* **Prompts** - Prompt-level analysis and response detail
* **Citations** - URL-level citation detail
* **Competitors** - Competitive citation landscape
* **Analytics** - Filtered charts and trend views
## Understanding Variability
AI Search results are not perfectly deterministic. Some response-to-response variability is normal.
That means:
* single responses are useful examples
* repeated runs are what make the trend credible
Focus on patterns across multiple runs rather than any one isolated answer.
## Troubleshooting
### No results appearing
If you do not see results:
* Confirm you have prompts configured
* Confirm at least one platform is enabled
* Confirm your brands, tracked URLs, and brand terms are present
### Presence seems unexpectedly low
If presence is lower than expected:
* Review tracked URLs for completeness
* Review brand terms for missing variations
* Check whether you are filtering too narrowly by date or platform
### Runs seem sparse
If results are not appearing as often as expected:
* Verify the project is fully configured
* Verify the account has an active qualifying plan
* Remember that execution is system-managed rather than user-triggered
## Next Steps
* **[Visibility Metrics](/search-tracking/visibility-metrics)** - Learn what the KPIs mean
* **[Platform Comparison](/search-tracking/platform-comparison)** - Compare results by platform
* **[AI Search Configuration](/search-tracking/search-configuration)** - Review and adjust project setup
# AI Search Configuration
Source: https://docs.devtune.ai/search-tracking/search-configuration
Understand the DevTune Project Settings structure for AI Search, including the General, Brands, Platforms, Content Preferences, and AI Traffic tabs and what each tab controls.
AI Search configuration is now centered on **Project Settings** rather than a collection of older standalone config tabs. This page explains how the current settings model works.
## Accessing Configuration
Navigate to **Project Settings** from the project sidebar.
The page includes these tabs:
* **General**
* **Brands**
* **Platforms**
* **Content Preferences** when enabled for your account
* **AI Traffic**
## General Tab
Use the **General** tab for the core project record:
* Project name
* Description
* Product context
This is the right place to update the product narrative DevTune uses when it evaluates relevance and generates recommendations.
## Brands Tab
The **Brands** tab combines what used to be separate areas for competitor setup, citation sources, and brand terms.
### Layout
The tab uses a master-detail pattern:
* The left side lists your primary brand and competitor brands
* The right side shows the selected brand's detail panel
### What you can manage
For each brand, you can manage:
* **Tracked URLs / citation sources**
* **Brand terms**
* **Brand type** (primary or competitor)
### Suggested competitors
Where DevTune has enough context, it can suggest relevant competitors to add. This helps teams move faster than manually building the competitor set from scratch.
## Platforms Tab
The **Platforms** tab controls which AI Search platforms DevTune queries during scheduled runs.
Supported platforms:
* ChatGPT
* Perplexity
* Gemini
* Google AI Mode
* Microsoft Bing Copilot
### Plan availability
* **Starter / Plus** - ChatGPT, Perplexity, Gemini
* **Pro / Agency / Enterprise** - All five platforms
Locked platforms remain visible so you can see what is available on higher tiers.
## Content Preferences Tab
The **Content Preferences** tab lets your team tell DevTune which content formats fit this project.
By default, every content format is allowed. When the tab is enabled for your account, you can:
* Allow only specific formats
* Block formats you do not want DevTune to recommend
* Add project-level style notes
Content preferences apply to Actions and generated briefs. For example, if comparison-style content is blocked, DevTune should avoid creating comparison recommendations and should reject manual brief-style requests for that blocked format.
## AI Traffic Tab
The **AI Traffic** tab is separate from AI Search, but it lives on the same Project Settings page because it shares the same project context.
Use it to:
* Generate the tracking snippet
* Copy installation code
* Enable or disable collection
## Why the Structure Changed
The current setup model is simpler than the older one:
* **Brands** is now the home for both tracked URLs and brand terms
* **Platforms** is isolated to runtime coverage
* **Content Preferences** controls the content formats DevTune may recommend when available
* **General** holds project context
* **AI Traffic** is kept nearby because it is another project-level signal surface
## Best Practices
* Review **General** whenever your product positioning changes
* Review **Brands** whenever you launch new content properties or start tracking a new competitor
* Review **Platforms** when you change plans or want to narrow scope
* Review **Content Preferences** when your content strategy changes or a format should no longer be recommended
* Treat **AI Traffic** as instrumentation, not just reporting
## Next Steps
* **[Tracked URLs](/search-tracking/domains)** - Manage tracked URLs inside the Brands tab
* **[Brand Terms](/search-tracking/keywords)** - Manage mention matching inside the Brands tab
* **[Prompts](/search-tracking/prompts)** - Manage the prompt side of AI Search tracking
* **[Running Search Tests](/search-tracking/running-search-tests)** - Understand what happens after setup
# AI Search Dashboard
Source: https://docs.devtune.ai/search-tracking/search-overview-dashboard
Use the AI Search Dashboard with primary KPI cards, presence and share-of-voice trend charts, and competitor highlights to move from signal to action.
The AI Search Dashboard is the high-level summary view for your project's search visibility. It is the fastest place to understand whether your presence is improving, where competitors are strongest, and which areas likely need attention.
## Accessing the Dashboard
Navigate to **AI Search** in your project sidebar, then open the **Dashboard** tab.
## Primary KPI Cards
At the top of the dashboard, DevTune highlights the core AI Search metrics:
### Overall Presence Rate
The percentage of completed AI responses that cite at least one URL tracked to your brand. Brand-name text without a tracked URL citation is reported separately under Brand Mentions.
### Share of Voice
Your share of total mentions and citations relative to tracked competitors.
### Sentiment Score
How positively or negatively AI platforms discuss your brand when they mention it.
## Secondary Metrics
Below the primary KPIs, DevTune surfaces more detailed measures such as:
* Docs presence
* Blog presence
* Brand mentions
* Top of answer
* Average citation rank
* Primary citation share
These help you understand not just whether you appear, but how and where.
## Trend Views
The dashboard uses trend views to show how your metrics move over time. Use these to answer:
* Are we improving or slipping?
* Is one platform moving differently from the others?
* Did a recent content or competitor change coincide with movement?
## Competitive Context
The dashboard also helps you see how your presence compares with tracked competitors. Use it as the top-level readout before going deeper into:
* **Prompts** for prompt-level performance
* **Citations** for URL-level detail
* **Competitors** for the competitive citation landscape
* **Analytics** for deeper filtered chart work
## Acting on the Dashboard
The dashboard is meant to route you into the next best workflow:
* Open **Prompts** when you need to inspect which query clusters are driving the numbers
* Open **Citations** when you need to see the exact cited URLs
* Open **Competitors** when you need the competitive landscape
* Open **Actions** when you are ready to turn the signal into work
## Best Practices
* Check the dashboard regularly for top-level direction
* Use it as a triage surface, not the only surface
* When a KPI changes materially, move immediately into Prompts, Citations, Competitors, or Timeline to explain why
## Next Steps
* **[Prompts](/search-tracking/prompts)** - Manage and inspect tracked queries
* **[Citations](/search-tracking/citations)** - View citation details
* **[Competitors](/search-tracking/competitors)** - Review the competitive citation landscape
* **[Analytics](/analytics/search-analytics)** - Explore deeper chart-based analysis
# AI Search Topics
Source: https://docs.devtune.ai/search-tracking/topics
Organize prompts into DevTune topics for thematic AI Search analysis, volume-weighted action recommendations, and opportunity scoring across your project.
Topics help you organize prompts into logical groups, making it easier to analyze AI search presence by theme and identify opportunities at a thematic level.
## What are Topics?
A topic is a category that groups related prompts together:
**Topic: "Discovery"**
* "What is the best data validation library for Python?"
* "Top schema validation tools"
* "Recommended API validation solutions"
**Topic: "Migration"**
* "Migrate from Pydantic v1 to v2"
* "Alternatives to Marshmallow for Python"
* "Replacing Cerberus with a modern validator"
Topics provide aggregate metrics across all prompts in the group, making it easier to see which themes perform well and where content investment is needed.
## Auto-Created Lifecycle Topics
When you create a project, DevTune automatically generates lifecycle topics based on common user journey stages:
* **Discovery** - Prompts about finding and exploring solutions in your category
* **Evaluation** - Prompts about comparing options and making decisions
* **Integration** - Prompts about setting up and implementing solutions
* **Migration** - Prompts about switching from one tool to another
* **Troubleshooting** - Prompts about solving problems and fixing issues
These lifecycle topics map to the stages users go through when adopting a tool. You can customize, rename, or delete them as needed.
## Why Use Topics?
### Thematic Analysis
See presence by theme:
* Which lifecycle stages show strong presence?
* Where are thematic gaps in your AI visibility?
* Which themes have the most competitive pressure?
### Volume-Weighted Recommendations
Topics aggregate data across prompts, and volume-weighted analysis accounts for the relative importance of each prompt. High-volume prompts within a topic have more influence on the topic-level metrics than low-volume prompts.
### Strategic Planning
Understand which areas of the user journey need attention:
* Strong Discovery presence but weak Integration presence suggests your content explains "what" but not "how"
* Strong Troubleshooting presence but weak Discovery presence means users find you when they have problems but not when they are exploring
## Creating and Managing Topics
### Creating a Topic
Navigate to **AI Search > Prompts** (topics are managed alongside prompts) or access topic management from the sidebar.
1. Click **Create Topic**
2. Enter a topic name
3. Add an optional description
4. Save
### Assigning Prompts to Topics
When creating or editing a prompt:
1. Select the topic from the dropdown
2. Save
You can also bulk-assign prompts to topics from the topic detail view.
### Editing Topics
Click on any topic to:
* Edit the topic name or description
* View all prompts assigned to the topic
* Review topic-level metrics
### Deleting Topics
Remove a topic by clicking the delete action. Deleting a topic does not delete the prompts assigned to it. Those prompts become unassigned and can be reassigned to other topics.
## Topic-Level Metrics
### Aggregate Presence Rate
The combined presence rate across all prompts in the topic. This shows how well your brand appears across the entire theme.
### Topic Share of Voice
Your share of voice within the topic, compared to competitor brands. This identifies which themes you dominate versus where competitors lead.
### Volume-Weighted Presence
Presence rate weighted by the estimated search volume of each prompt. High-volume prompts contribute more to this metric, reflecting their greater real-world impact.
### Opportunity Score
Each topic receives an opportunity score that factors in:
* Current presence rate (lower presence = more room to improve)
* Estimated aggregate volume (higher volume = more potential impact)
* Competition level (lower competition = easier to improve)
* Trend direction (declining presence = more urgent)
Topics with high opportunity scores represent the best candidates for content investment.
### Prompt Count
The number of prompts assigned to the topic. Topics with very few prompts may not provide reliable aggregate data.
## Topic Organization Strategies
### By Lifecycle Stage
The default auto-created topics follow this pattern:
* **Discovery** - "Best \[category] tools", "What is \[category]?"
* **Evaluation** - "\[Product] vs \[Competitor]", "Compare \[options]"
* **Integration** - "How to set up \[product]", "\[Product] quickstart"
* **Migration** - "Migrate from \[competitor]", "\[Competitor] alternatives"
* **Troubleshooting** - "Fix \[error] in \[product]", "\[Product] performance issues"
### By Feature Area
Organize by product capabilities:
* **Authentication** - Auth-related queries
* **Data Processing** - Data handling queries
* **API Integration** - API connection queries
### By Audience
Organize by target user type:
* **Beginners** - Entry-level queries
* **Enterprise** - Business and scale-focused queries
* **Specific Language** - Language or framework-specific queries
## Best Practices
### Balanced Topic Sizes
Aim for 5-15 prompts per topic. Topics that are too small may not provide meaningful aggregate data. Topics that are too large may mix unrelated themes.
### Clear, Descriptive Names
Use names that clearly indicate the theme:
* "Getting Started Guides" - Clear
* "Topic 1" - Not helpful
### Assign All Prompts
Review your prompt list periodically and assign any unassigned prompts to topics. Unassigned prompts are still tracked individually but do not contribute to topic-level analysis.
### Use Opportunity Scores for Prioritization
When deciding where to invest content effort, sort topics by opportunity score. The highest-opportunity topics offer the best combination of room for improvement, high volume, and low competition.
## Topics and Analytics
### Filtered Dashboard Views
Use topics to filter the AI Search dashboard. Select a topic to see all metrics scoped to just the prompts in that topic.
### Cross-Topic Comparison
Compare topic-level metrics side by side to understand which areas of the user journey are strongest and weakest for your brand.
## Next Steps
* **[Prompts](/search-tracking/prompts)** - Manage individual prompts
* **[Tracked URLs](/search-tracking/domains)** - Configure the URLs DevTune attributes to brands
* **[Understanding Metrics](/search-tracking/visibility-metrics)** - How topic data feeds into metrics
* **[Search Dashboard](/search-tracking/search-overview-dashboard)** - View topic-filtered results
# AI Search Visibility Metrics
Source: https://docs.devtune.ai/search-tracking/visibility-metrics
Deep dive into DevTune AI Search metrics: presence rate, share of voice, sentiment, citation metrics, top-of-answer rate, and coverage confidence scoring.
DevTune provides a comprehensive set of metrics to measure your AI search presence. This guide explains each metric, how it is calculated, and how to interpret it.
## Primary KPIs
These three metrics are your top-level indicators of AI search presence.
### Overall Presence Rate
Your primary metric for AI search visibility.
**Definition:**
The percentage of completed AI responses that cite at least one URL tracked to your brand. A response counts once, whether it cites one tracked URL or several.
**Calculation:**
```
Overall Presence Rate = (Responses citing your tracked URLs / Completed responses) x 100
```
**Example:**
* 100 completed responses across all platforms
* Your tracked URLs were cited in 45 responses
* Overall Presence Rate: 45%
**Interpretation:**
* 70%+ = Strong presence. AI platforms consistently surface your brand.
* 50-69% = Moderate presence. Visible in many queries but with significant gaps.
* 30-49% = Developing presence. Content improvement will have significant impact.
* Below 30% = Early stage. Focused content creation is the priority.
### Share of Voice
Your brand's share of total AI search mentions relative to competitor brands.
**Definition:**
The proportion of all brand mentions and citations (yours plus competitors) that belong to your brand.
**Calculation:**
```
Share of Voice = (Your mentions + Your citations) / (Total mentions + Total citations across all brands) x 100
```
**Example:**
* Your brand: 120 mentions and citations
* Competitor A: 80 mentions and citations
* Competitor B: 50 mentions and citations
* Total: 250
* Your Share of Voice: 48%
**Interpretation:**
* Share of Voice above 40% indicates market leadership in AI search.
* Compare to your actual market position. If your market share is 30% but your AI search Share of Voice is 15%, there is room to improve AI visibility.
* Track Share of Voice trends to see whether you are gaining or losing ground relative to competitors.
### Sentiment Score
How positively or negatively AI platforms discuss your brand.
**Definition:**
An aggregate score representing the tone of AI responses that mention your brand. Sentiment analysis evaluates whether mentions are positive, neutral, or negative.
**Interpretation:**
* Positive sentiment means AI platforms describe your product favorably
* Neutral sentiment means factual, balanced mentions
* Negative sentiment may indicate known issues, common complaints, or unfavorable comparisons
* Sudden sentiment changes warrant investigation
## Secondary Metrics
Six secondary metrics provide deeper analytical capability.
### Docs Presence
**Definition:**
The rate at which citation sources tagged as "docs" appear in AI responses. This measures how well your documentation is recognized and cited by AI platforms.
**Usage:**
Compare Docs Presence to overall presence. If your docs are cited less than your marketing site, it may indicate documentation quality or discoverability issues.
### Blog Presence
**Definition:**
The rate at which citation sources tagged as "blog" appear in AI responses. This measures how well your blog content is surfaced by AI platforms.
**Usage:**
Blog presence indicates whether your content marketing is reaching AI-mediated audiences. High blog presence suggests your blog content is authoritative and well-indexed.
### Brand Mentions
**Definition:**
The rate at which AI responses contain your brand terms (name mentions) regardless of whether citation URLs are present.
**Calculation:**
```
Brand Mention Rate = (Completed responses with brand term matches / Completed responses) x 100
```
**Usage:**
Brand mentions capture visibility that citation-based presence intentionally does not include. If an AI response says, "You could use DataForge" without linking to dataforge.io, the Brand Mention metric records it, while Overall Presence Rate does not.
### Top of Answer
**Definition:**
The rate at which your brand appears in the first position or opening section of an AI response. Being mentioned first or at the top of an AI response carries more weight than appearing later.
**Calculation:**
```
Top of Answer Rate = (Prompts where your brand appears first / Prompts where your brand appears) x 100
```
**Usage:**
High Top of Answer rate means AI platforms consider your brand a primary recommendation, not just an also-mentioned option.
### Avg Citation Rank
**Definition:**
Your average position among cited sources when your citation sources appear. A rank of 1 means you are the first-cited source. Lower numbers are better.
**Usage:**
Citation rank indicates how prominently your content is featured among sources. A low average rank means AI platforms cite you early and prominently.
### Primary Citation Share
**Definition:**
The proportion of all citations that point to your primary citation sources versus competitor citation sources and other sources.
**Calculation:**
```
Primary Citation Share = (Citations to your citation sources / Total citations) x 100
```
**Usage:**
Primary Citation Share measures how much of the citation real estate belongs to you. This is complementary to Share of Voice, which includes brand mentions.
## Coverage Confidence
### Wilson Score Interval
DevTune uses a Wilson score confidence interval to indicate how reliable each metric is given the sample size.
**Why this matters:**
If you have only collected 10 completed responses, a presence rate of 50% is much less reliable than if you had collected 200 responses. The Wilson score interval provides a lower and upper bound for the true metric value based on sample size.
**How to read it:**
* A narrow confidence interval (e.g., 45%-55%) means the metric is reliable
* A wide confidence interval (e.g., 20%-80%) means more data is needed
* As you accumulate more test runs, confidence intervals narrow
## Trailing Window Analysis
Metrics are calculated over trailing time windows to smooth out variability between individual test runs.
**Available windows:**
* 7-day trailing window for recent performance
* 30-day trailing window for monthly trends
* 90-day trailing window for quarterly assessment
Trailing windows ensure that a single anomalous test run does not distort your understanding of current performance.
## Position Distribution
Beyond average metrics, DevTune tracks the distribution of where your brand appears in AI responses.
**Position categories:**
* **First mention** - Your brand appears before any other brand
* **Early mention** - Your brand appears in the first third of the response
* **Mid mention** - Your brand appears in the middle section
* **Late mention** - Your brand appears toward the end
* **Not present** - Your brand does not appear
Position distribution helps you understand not just whether you appear, but how prominently you appear.
## Platform-Specific Metrics
All metrics are available per platform. Each platform may show different results because:
* Platforms have different training data and knowledge bases
* Citation behavior varies by platform
* Brand mention patterns differ
* Response structure and length vary
Use per-platform metrics to identify:
* Your strongest platforms
* Platforms needing content improvement
* Where competitors outperform you by platform
## Prompt-Level Metrics
All metrics are also available per prompt. This granularity helps you:
* Identify which prompts produce the strongest presence
* Find prompts where competitors dominate
* Discover content gaps at the individual query level
## Understanding Metric Relationships
### High Presence Rate, Low Citation Share
Your brand is mentioned frequently but specific URLs are not cited. This may indicate:
* AI platforms know about your brand but do not reference specific pages
* Content is recognized but not structured for citation
* Brand awareness is stronger than content depth
### High Citation Share, Lower Presence Rate
When present, your citations dominate, but you are not present in many prompts. This indicates:
* Strong content quality for covered topics
* Gaps in topic coverage
* Focus on expanding prompt coverage
### Platform Divergence
Large differences between platforms suggest platform-specific content opportunities. A platform where you are weak may respond to different content approaches than your strong platforms.
## Setting Goals
### Realistic Targets
Set metric goals based on your current baseline:
* A 5-10% improvement in Overall Presence Rate per quarter is a strong target
* Share of Voice targets should be benchmarked against your actual market position
* Sentiment goals should focus on maintaining positive or improving from neutral
### Tracking Progress
Review metrics weekly for short-term trends and monthly for strategic assessment. Use the trailing window analysis to filter out noise and identify genuine progress.
## Next Steps
* **[Platform Comparison](/search-tracking/platform-comparison)** - Deep dive by platform
* **[Prompts](/search-tracking/prompts)** - Manage tracked queries
* **[Citations](/search-tracking/citations)** - Understand citation details
* **[Search Dashboard](/search-tracking/search-overview-dashboard)** - View metrics in context