> ## Documentation Index
> Fetch the complete documentation index at: https://developer.dashsocial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Track social listening trends with graph report

> Track social listening metrics over time with daily or monthly granularity.

Use graph reports to track how social listening metrics change over time. Pull daily or monthly time-series data to visualize conversation trends, measure campaign momentum, and analyze brand mention patterns in BI tools like Power BI, Tableau, or Looker.

<Note>
  The Social Listening report provides aggregated metrics only. For full access to individual posts, top keywords, sentiment breakdowns, and web results, use the [Social Listening API](/guides/social-listening/monitor-brand-mentions-with-social-listening-api).
</Note>

## Use cases

Tracking conversation volume and engagement over time reveals campaign impact and identifies momentum shifts. Graph reports provide day-by-day or month-by-month breakdowns for trend analysis.

<CardGroup cols={2}>
  <Card title="Campaign momentum tracking">
    Chart daily engagement and post volume during product launches to measure conversation growth
  </Card>

  <Card title="Brand health monitoring">
    Track engagement trends to identify when brand conversations gain or lose momentum
  </Card>

  <Card title="Competitive trend analysis">
    Compare monthly metrics against previous periods to benchmark performance
  </Card>

  <Card title="Executive reporting">
    Visualize social listening KPIs in Tableau or Power BI for stakeholder dashboards
  </Card>
</CardGroup>

## Before you start

Make sure you have:

* **API Key**: Your authentication token
* **Brand ID**: The brand to track social listening data for

See our [API Quickstart](https://developer.dashsocial.com/guides/get-started/quickstart) for help getting these.

<Info>
  **Need to create a topic?** See [Monitor Brand Mentions with Social Listening API](/guides/monitor-brand-mentions-with-social-listening-api) to set up your first topic.
</Info>

***

## Implementation

### Step 1: Get your topic ID

Retrieve your topic ID to identify which conversation to analyze.

```http theme={null}
GET https://listening.dashsocial.com/organizations/{organization_id}/topics
```

#### Key query parameters

* `organization_id`: Your organization's unique ID

If you don't have your organization ID, call `GET https://auth.dashsocial.com/api/self` using your API key:

```bash theme={null}
curl 'https://auth.dashsocial.com/api/self' \
  -H 'Authorization: Bearer {token}'
```

Sample response:

```json theme={null}
{
    "accessible_brands": [144],
    "brands": {
        "your-brand": {
            "id": 144,
            "name": "Your Brand",
            "organization": {
                "id": 1,
                "name": "Your Organization"
            },
            "organization_id": 1
        }
    },
    "organization": {
        "id": 1,
        "name": "Your Organization"
    },
    "organization_id": 1
}
```

Look for `organization_id` at the top level of the response.

Sample response:

```json theme={null}
{
    "data": [
        {
            "id": 11423,
            "name": "New cosmetic release 2025",
            "audience_type": "PUBLIC",
            "selected_brand_id": 144,
            "search_body": {
                "filters": {
                    "keywords_and_hashtags": "((new release 2025) AND (cosmetics))"
                }
            }
        }
    ]
}
```

Save the `id` value. This is your `topic_id` for all subsequent requests.

<Info>
  **Already have a topic ID?** Skip to Step 2.
</Info>

### Step 2: Map your parameters

Review the available parameters before making your API call:

<Table>
  <thead>
    <tr>
      <th>
        Parameter
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `brand_ids`
      </td>

      <td>
        Your brand ID from the UI
      </td>
    </tr>

    <tr>
      <td>
        `channels`
      </td>

      <td>
        Platform to query:

        * Instagram: `INSTAGRAM`
        * TikTok: `TIKTOK`
        * Facebook: `FACEBOOK`
        * YouTube: `YOUTUBE`
        * LinkedIn: `LINKEDIN`
        * X: `TWITTER`
        * Web: `WEB`
        * Reddit: `REDDIT`
      </td>
    </tr>

    <tr>
      <td>
        `metrics`
      </td>

      <td>
        Social listening metrics available for all channels:

        * Avg. Engagements: `AVERAGE_ENGAGEMENTS_PER_POST`
        * Avg. Mentions: `AVG_MENTIONS_TOPIC`
        * Engagements: `TOTAL_ENGAGEMENTS_TOPIC`
        * Mentions: `TOTAL_MENTIONS_TOPIC`
        * Net Sentiment: `NET_SENTIMENT`

        See [Available Metrics](#available-metrics) for full descriptions.

        Request multiple metrics by separating with commas
      </td>
    </tr>

    <tr>
      <td>
        `start_date` / `end_date`
      </td>

      <td>
        Reporting date range in YYYY-MM-DD format
      </td>
    </tr>

    <tr>
      <td>
        `context_start_date` / `context_end_date`
      </td>

      <td>
        Comparison date range for period-over-period analysis. Optional
      </td>
    </tr>

    <tr>
      <td>
        `report_type`
      </td>

      <td>
        Set to `TOTAL_METRIC` for aggregated totals
      </td>
    </tr>

    <tr>
      <td>
        `listening.topic_ids` *(body)*
      </td>

      <td>
        Array of topic IDs from Step 1 (e.g., `[11423]`). Pass multiple IDs to query multiple topics at once
      </td>
    </tr>
  </tbody>
</Table>

***

### Step 3: Make the API call

Send a PUT request using the parameters from Step 2 and the topic ID from Step 1. This example retrieves daily average engagements per post for topic `11423` on Instagram from May 1-7, with April 1-7 as the comparison period.

```http theme={null}
PUT https://dashboard.dashsocial.com/reports/data
  ?channels=INSTAGRAM
  &brand_ids=144
  &start_date=2025-05-01
  &end_date=2025-05-07
  &context_start_date=2025-04-01
  &context_end_date=2025-04-07
  &metrics=AVERAGE_ENGAGEMENTS_PER_POST
  &report_type=TOTAL_METRIC
body = {
  "listening": {
    "topic_ids": [11423]
  }
}
```

Sample response:

```json theme={null}
{
    "data": {
        "144": {
            "avatar": "https://cdn.dashsocial.com/avatars/2306810931.jpeg",
            "data_type": "BRAND",
            "name": "sunny.today",
            "user_has_access": true
        },
        "TOPIC_11423": {
            "data_type": "TOPIC",
            "metrics": {
                "AVERAGE_ENGAGEMENTS_PER_POST": {
                    "ALL_CHANNELS": {
                        "2025-05-01 00:00:00": 614,
                        "2025-05-02 00:00:00": 466,
                        "2025-05-03 00:00:00": 467,
                        "2025-05-04 00:00:00": 670,
                        "2025-05-05 00:00:00": 329,
                        "2025-05-06 00:00:00": 664,
                        "2025-05-07 00:00:00": 823
                    }
                }
            }
        },
        "metrics": {
            "AVERAGE_ENGAGEMENTS_PER_POST": {
                "ALL_CHANNELS": {
                    "2025-05-01 00:00:00": 614,
                    "2025-05-02 00:00:00": 466,
                    "2025-05-03 00:00:00": 467,
                    "2025-05-04 00:00:00": 670,
                    "2025-05-05 00:00:00": 329,
                    "2025-05-06 00:00:00": 664,
                    "2025-05-07 00:00:00": 823
                }
            }
        }
    },
    "product_category": "LISTENING"
}
```

<Info>
  **Understanding the response:** Topic data is nested under `TOPIC_{id}`. Brand metadata appears at the top level under the brand ID. Metric values are organized by date with daily breakdowns (e.g., May 1 had 614 average engagements, May 7 had 823).
</Info>

<Warning>
  **Date format matters:** Always use `YYYY-MM-DD` format for dates (e.g., `2025-05-01`). Other formats will cause errors.
</Warning>

***

## Metrics

<Tabs>
  <Tab title="Instagram">
    | Metric Name      | Description                                                                                                                                                           | Metric API Name                |
    | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
    | Avg. Engagements | The estimated average number of engagements per post within this Topic that were published during the reporting period                                                | `AVERAGE_ENGAGEMENTS_PER_POST` |
    | Avg. Impressions | The estimated average number of impressions per post within this Topic during the reporting period. Impressions are estimated for Facebook, Instagram, X and Youtube. | `AVERAGE_IMPRESSIONS_PER_POST` |
    | Avg. Mentions    | The estimated number of posts published per day within this Topic during the reporting period                                                                         | `AVG_MENTIONS_TOPIC`           |
    | Net Sentiment    | The net sentiment of post captions within this Topic during the reporting period. Net sentiment shows the overall balance between positive and negative conversation. | `NET_SENTIMENT`                |
    | Engagements      | The estimated number of engagements on posts within this Topic that were published during the reporting period                                                        | `TOTAL_ENGAGEMENTS_TOPIC`      |
    | Impressions      | The estimated number of impressions on posts within this Topic during the reporting period. Impressions are estimated for Facebook, Instagram, X and Youtube.         | `TOTAL_IMPRESSIONS_TOPIC`      |
    | Mentions         | The estimated number of posts published within this Topic during the reporting period                                                                                 | `TOTAL_MENTIONS_TOPIC`         |
  </Tab>

  <Tab title="TikTok">
    | Metric Name      | Description                                                                                                                                                           | Metric API Name                |
    | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
    | Avg. Engagements | The estimated average number of engagements per post within this Topic that were published during the reporting period                                                | `AVERAGE_ENGAGEMENTS_PER_POST` |
    | Avg. Mentions    | The estimated number of posts published per day within this Topic during the reporting period                                                                         | `AVG_MENTIONS_TOPIC`           |
    | Net Sentiment    | The net sentiment of post captions within this Topic during the reporting period. Net sentiment shows the overall balance between positive and negative conversation. | `NET_SENTIMENT`                |
    | Engagements      | The estimated number of engagements on posts within this Topic that were published during the reporting period                                                        | `TOTAL_ENGAGEMENTS_TOPIC`      |
    | Mentions         | The estimated number of posts published within this Topic during the reporting period                                                                                 | `TOTAL_MENTIONS_TOPIC`         |
  </Tab>

  <Tab title="Facebook">
    | Metric Name      | Description                                                                                                                                                           | Metric API Name                |
    | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
    | Avg. Engagements | The estimated average number of engagements per post within this Topic that were published during the reporting period                                                | `AVERAGE_ENGAGEMENTS_PER_POST` |
    | Avg. Impressions | The estimated average number of impressions per post within this Topic during the reporting period. Impressions are estimated for Facebook, Instagram, X and Youtube. | `AVERAGE_IMPRESSIONS_PER_POST` |
    | Avg. Mentions    | The estimated number of posts published per day within this Topic during the reporting period                                                                         | `AVG_MENTIONS_TOPIC`           |
    | Net Sentiment    | The net sentiment of post captions within this Topic during the reporting period. Net sentiment shows the overall balance between positive and negative conversation. | `NET_SENTIMENT`                |
    | Engagements      | The estimated number of engagements on posts within this Topic that were published during the reporting period                                                        | `TOTAL_ENGAGEMENTS_TOPIC`      |
    | Impressions      | The estimated number of impressions on posts within this Topic during the reporting period. Impressions are estimated for Facebook, Instagram, X and Youtube.         | `TOTAL_IMPRESSIONS_TOPIC`      |
    | Mentions         | The estimated number of posts published within this Topic during the reporting period                                                                                 | `TOTAL_MENTIONS_TOPIC`         |
  </Tab>

  <Tab title="Youtube">
    | Metric Name      | Description                                                                                                                                                           | Metric API Name                |
    | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
    | Avg. Engagements | The estimated average number of engagements per post within this Topic that were published during the reporting period                                                | `AVERAGE_ENGAGEMENTS_PER_POST` |
    | Avg. Impressions | The estimated average number of impressions per post within this Topic during the reporting period. Impressions are estimated for Facebook, Instagram, X and Youtube. | `AVERAGE_IMPRESSIONS_PER_POST` |
    | Avg. Mentions    | The estimated number of posts published per day within this Topic during the reporting period                                                                         | `AVG_MENTIONS_TOPIC`           |
    | Net Sentiment    | The net sentiment of post captions within this Topic during the reporting period. Net sentiment shows the overall balance between positive and negative conversation. | `NET_SENTIMENT`                |
    | Engagements      | The estimated number of engagements on posts within this Topic that were published during the reporting period                                                        | `TOTAL_ENGAGEMENTS_TOPIC`      |
    | Impressions      | The estimated number of impressions on posts within this Topic during the reporting period. Impressions are estimated for Facebook, Instagram, X and Youtube.         | `TOTAL_IMPRESSIONS_TOPIC`      |
    | Mentions         | The estimated number of posts published within this Topic during the reporting period                                                                                 | `TOTAL_MENTIONS_TOPIC`         |
  </Tab>

  <Tab title="LinkedIn">
    | Metric Name      | Description                                                                                                                                                           | Metric API Name                |
    | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
    | Avg. Engagements | The estimated average number of engagements per post within this Topic that were published during the reporting period                                                | `AVERAGE_ENGAGEMENTS_PER_POST` |
    | Avg. Mentions    | The estimated number of posts published per day within this Topic during the reporting period                                                                         | `AVG_MENTIONS_TOPIC`           |
    | Net Sentiment    | The net sentiment of post captions within this Topic during the reporting period. Net sentiment shows the overall balance between positive and negative conversation. | `NET_SENTIMENT`                |
    | Engagements      | The estimated number of engagements on posts within this Topic that were published during the reporting period                                                        | `TOTAL_ENGAGEMENTS_TOPIC`      |
    | Mentions         | The estimated number of posts published within this Topic during the reporting period                                                                                 | `TOTAL_MENTIONS_TOPIC`         |
  </Tab>

  <Tab title="X">
    | Metric Name      | Description                                                                                                                                                           | Metric API Name                |
    | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
    | Avg. Engagements | The estimated average number of engagements per post within this Topic that were published during the reporting period                                                | `AVERAGE_ENGAGEMENTS_PER_POST` |
    | Avg. Impressions | The estimated average number of impressions per post within this Topic during the reporting period. Impressions are estimated for Facebook, Instagram, X and Youtube. | `AVERAGE_IMPRESSIONS_PER_POST` |
    | Avg. Mentions    | The estimated number of posts published per day within this Topic during the reporting period                                                                         | `AVG_MENTIONS_TOPIC`           |
    | Net Sentiment    | The net sentiment of post captions within this Topic during the reporting period. Net sentiment shows the overall balance between positive and negative conversation. | `NET_SENTIMENT`                |
    | Engagements      | The estimated number of engagements on posts within this Topic that were published during the reporting period                                                        | `TOTAL_ENGAGEMENTS_TOPIC`      |
    | Impressions      | The estimated number of impressions on posts within this Topic during the reporting period. Impressions are estimated for Facebook, Instagram, X and Youtube.         | `TOTAL_IMPRESSIONS_TOPIC`      |
    | Mentions         | The estimated number of posts published within this Topic during the reporting period                                                                                 | `TOTAL_MENTIONS_TOPIC`         |
  </Tab>

  <Tab title="Web">
    | Metric Name      | Description                                                                                                                                                           | Metric API Name                |
    | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
    | Avg. Engagements | The estimated average number of engagements per post within this Topic that were published during the reporting period                                                | `AVERAGE_ENGAGEMENTS_PER_POST` |
    | Avg. Mentions    | The estimated number of posts published per day within this Topic during the reporting period                                                                         | `AVG_MENTIONS_TOPIC`           |
    | Net Sentiment    | The net sentiment of post captions within this Topic during the reporting period. Net sentiment shows the overall balance between positive and negative conversation. | `NET_SENTIMENT`                |
    | Engagements      | The estimated number of engagements on posts within this Topic that were published during the reporting period                                                        | `TOTAL_ENGAGEMENTS_TOPIC`      |
    | Mentions         | The estimated number of posts published within this Topic during the reporting period                                                                                 | `TOTAL_MENTIONS_TOPIC`         |
  </Tab>

  <Tab title="Reddit">
    | Metric Name      | Description                                                                                                                                                           | Metric API Name                |
    | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
    | Avg. Engagements | The estimated average number of engagements per post within this Topic that were published during the reporting period                                                | `AVERAGE_ENGAGEMENTS_PER_POST` |
    | Avg. Mentions    | The estimated number of posts published per day within this Topic during the reporting period                                                                         | `AVG_MENTIONS_TOPIC`           |
    | Net Sentiment    | The net sentiment of post captions within this Topic during the reporting period. Net sentiment shows the overall balance between positive and negative conversation. | `NET_SENTIMENT`                |
    | Engagements      | The estimated number of engagements on posts within this Topic that were published during the reporting period                                                        | `TOTAL_ENGAGEMENTS_TOPIC`      |
    | Mentions         | The estimated number of posts published within this Topic during the reporting period                                                                                 | `TOTAL_MENTIONS_TOPIC`         |
  </Tab>
</Tabs>

## Next steps

Use your time-series data to:

* **Visualize trends**: Import data into Power BI, Tableau, or Looker to create executive dashboards
* **Identify momentum shifts**: Compare daily or monthly metrics to spot when conversations accelerate or decline
* **Measure campaign impact**: Track metrics before, during, and after campaigns to quantify effectiveness
* **Compare time periods**: Use context dates to benchmark current performance against historical data

<Warning>
  **Data freshness:** Metric updates vary by post age. Recently published posts refresh more frequently than older content. Focus on data from the last 90 days for the most accurate reporting.
</Warning>

<Info>
  **Other social listening reports:** This guide covers graph reports for time-series data. Social listening also supports:

  * [Metric reports](/guides/get-aggregated-social-listening-metrics) for aggregated totals
  * [Social Listening API](/guides/monitor-brand-mentions-with-social-listening-api) for detailed post-level data
</Info>