Custom dashboard

Build a dashboard that keeps each API surface’s metric scope visible. This guide uses the reusable client from the Quick start.

Fetch the overview

Request performance, competitors, and source domains with the same period. Keep the returned methodology with the displayed scores so readers can see the response and provider scope.

async function fetchDashboardData(client, brandId, period = 30) {
  const [performance, competitorData, sourceData] = await Promise.all([
    client.getPerformance(brandId, { period }),
    client.getCompetitors(brandId, {
      period,
      relationship: 'SELF,DIRECT',
      limit: 100,
      sort: 'shareOfVoice',
      order: 'desc',
    }),
    client.getSourceDomains(brandId, {
      period,
      limit: 20,
      sort: 'mentions',
      order: 'desc',
    }),
  ]);

  const self = competitorData.competitors.find(
    (item) => item.relationship === 'SELF'
  );
  const direct = competitorData.competitors.filter(
    (item) => item.relationship === 'DIRECT'
  );

  return {
    scores: performance.scores,
    methodology: performance.methodology,
    self: self ?? null,
    competitors: direct.map((item) => ({
      id: item.id,
      name: item.name,
      mentions: item.totalMentions,
      shareOfVoice: item.shareOfVoice,
      shareOfVoiceGap: self
        ? Number((item.shareOfVoice - self.shareOfVoice).toFixed(2))
        : null,
    })),
    sources: sourceData.sources.map((item) => ({
      domain: item.domain,
      citations: item.totalMentions,
      citationShare: item.rate,
      isSelf: item.isSelf,
    })),
  };
}

def fetch_dashboard_data(client, brand_id: str, period: int = 30) -> dict:
    performance = client.get_performance(brand_id, period=period)
    competitor_data = client.get_competitors(
        brand_id, period=period, limit=100,
        sort='shareOfVoice', order='desc',
    )
    source_data = client.get_source_domains(
        brand_id, period=period, limit=20,
        sort='mentions', order='desc',
    )

    self_brand = next(
        (item for item in competitor_data['competitors']
         if item['relationship'] == 'SELF'),
        None,
    )
    direct = [
        item for item in competitor_data['competitors']
        if item['relationship'] == 'DIRECT'
    ]

    return {
        'scores': performance['scores'],
        'methodology': performance['methodology'],
        'self': self_brand,
        'competitors': [
            {
                'id': item['id'],
                'name': item['name'],
                'mentions': item['totalMentions'],
                'share_of_voice': item['shareOfVoice'],
                'share_of_voice_gap': round(
                    item['shareOfVoice'] - self_brand['shareOfVoice'], 2
                ) if self_brand else None,
            }
            for item in direct
        ],
        'sources': [
            {
                'domain': item['domain'],
                'citations': item['totalMentions'],
                'citation_share': item['rate'],
                'is_self': item['isSelf'],
            }
            for item in source_data['sources']
        ],
    }

The Python client in the Quick start does not expose the relationship argument. Filter the returned list as shown, or extend the wrapper to pass that query parameter.

Label the metrics by surface

Do not replace these definitions with similarly named dashboard, export, MCP, or Looker Studio formulas.

Field	REST performance scope
`scores.mentionRate`	SELF-mentioned answers divided by answers with a SELF or DIRECT mention
`scores.sourceRate`	SELF-citing answers divided by answers with a SELF or DIRECT citation
`scores.coverage`	SELF-mentioned answers divided by all answers in the selected API scope
`scores.shareOfVoice`	SELF mention occurrences divided by SELF plus DIRECT occurrences
`scores.sentiment`	Average SELF sentiment on the `0` to `100` scale

Show methodology.responsesTotal, methodology.promptsCount, and methodology.providers near the score cards. A change in those values can make two periods non-comparable.

Add response diagnostics

The Answers endpoint applies hasSelfSource=true, but currently ignores the inverse value false. Request SELF-mentioned answers and filter the returned hasSelfSource flag in your client.

JavaScript

async function fetchDiagnostics(client, brandId, period = 30) {
  const [answerData, searchData] = await Promise.all([
    client.getAnswers(brandId, {
      period,
      hasSelfMention: true,
      limit: 100,
      sort: 'createdAt',
      order: 'desc',
    }),
    client.getSearch(brandId, {
      period,
      limit: 20,
      sort: 'occurrences',
      order: 'desc',
    }),
  ]);

  return {
    sampledMentionWithoutCitation: answerData.answers
      .filter((answer) => !answer.hasSelfSource)
      .map((answer) => ({
        prompt: answer.promptText,
        provider: answer.provider,
        position: answer.selfMentionPosition,
      })),
    queryFanOut: searchData.searches.map((record) => ({
      query: record.query,
      occurrences: record.occurrences,
      prompts: record.prompts.map((prompt) => prompt.text),
      models: record.models,
    })),
  };
}

The answer diagnostic is limited to the requested page. Its length is not the total number of matching answers. Paginate before calculating a complete count.

Verify the dashboard

Display the selected period and API methodology.
Confirm that SELF and DIRECT relationships are not mixed with other competitor types.
Treat a Share of Voice gap as a difference in the selected answer set, not market share.
Keep answer citations, query fan-out, and competitor mentions as separate observations.
Compare equivalent filters and prompt sets before labeling a trend.

Get started

Configure data

Monitor and measure

Analyze and act

Agency and automation

Implementation guides

Fetch the overview

Label the metrics by surface

Add response diagnostics

Verify the dashboard

​Fetch the overview

​Label the metrics by surface

​Add response diagnostics

​Verify the dashboard

​Related pages

Fetch the overview

Label the metrics by surface

Add response diagnostics

Verify the dashboard

Related pages