---
title: "Project Mindshare Time Series"
method: GET
path: "/gateway/v1/social/mindshare"
tags: ["Social"]
---

# Project Mindshare Time Series

`GET /gateway/v1/social/mindshare`

## Request

- Base URL: `https://api.asksurf.ai`
- URL: `https://api.asksurf.ai/gateway/v1/social/mindshare`
- Auth: HTTP bearer

Returns project social view-count time series, grouped by the required interval (5m, 1h, 1d, or 7d). Provide exactly one of id (Surf project UUID) or q (project name). Optional from/to accept Unix seconds or date strings; omitted to defaults to the current interval boundary, and omitted from defaults to 30 days before to. No pagination or time_range parameter. Source defaults to x; binance_square is also supported. Set include_tag_percents=true for per-tag percentage series and optional ranking snapshots. This measures attention, not sentiment.

## Query parameters

- `id` string: Surf project UUID. Provide one of `id` or `q`.
- `q` string: Entity name to resolve like `uniswap`, `ethereum`, or `aave`. Provide one of `id` or `q`.
- `interval` '5m' | '1h' | '1d' | '7d', required: Bucket size for each point in the returned time-series: `5m`, `1h`, `1d`, or `7d`. This is NOT a window — the default window is 30 days; pass `from`/`to` to bound the range. Not the same parameter as `time_range` (which does not exist on this endpoint). Note: when `include_tag_percents=true`, `5m` falls back to hourly data for the per-tag series (Argus has no 5m granularity for tag percentages).
- `from` string: Start timestamp. Accepts Unix seconds (1704067200) or date string (2024-01-01)
- `to` string: End timestamp. Accepts Unix seconds (1706745600) or date string (2024-02-01)
- `include_tag_percents` boolean: Set to `true` to additionally return per-tag mindshare percentage time-series in the `tag_percents` field. A project can belong to multiple tags; each tag returns its own sparse time-series (values are 0~100 percentages, not ratios). Default `false` — response shape is byte-identical to the legacy format.
- `source` 'x' | 'binance_square': Data lane: `x` (X/Twitter, default) or `binance_square` (Binance Square). Response shape is identical across sources.

## Response `200`

OK

- SocialMindshareBody
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `data` SocialMindsharePoint[], nullable, required
    - `timestamp` integer, required: Unix timestamp in seconds
    - `value` integer, required: Mindshare view count at this timestamp
  - `meta` OffsetMeta, required
    - `cached` boolean, required: Whether this response was served from cache
    - `credits_used` integer, required: Credits deducted for this request
    - `empty_reason` string: Hint explaining why the data array is empty, when applicable
    - `has_more` boolean: Whether more items may exist beyond this response. For offset-paged endpoints, continue with a larger offset. For time-series endpoints without offset/cursor controls, true means the requested time range hit an upstream cap; narrow from/to to continue. Omitted when exhaustion cannot be proven.
    - `limit` integer, required: Maximum number of items returned in this response
    - `offset` integer, required: Number of items skipped (pagination offset)
    - `total` integer: Total number of matching items (before pagination). Omitted when total is unknown.
    - `watermark` integer: Warehouse watermark (Unix seconds) this response was computed at, on warehouse-backed endpoints (e.g. Hyperliquid /trades/aggregate) — rows up to this time come from the warehouse, newer rows from the live tail. Omitted elsewhere.
  - `tag_percents` ProjectTagMindshareSeries[]: Per-tag mindshare percentage time-series. Only present when `include_tag_percents=true` was passed. Empty array means the project has no tag data; omitted means the field was not requested. Tags are sorted by the last point's percent descending, with tag-name ascending as tiebreaker.
    - `points` MindshareTagPercentPoint[], nullable, required: Sparse time-series of this tag's mindshare percentage
      - `percent` number, double, required: Project share within this tag at this timestamp, scaled 0~100 (e.g. 15.23 = 15.23%)
      - `timestamp` integer, required: Bucket start Unix timestamp in seconds
    - `rank` integer: Project's rank within this tag (1 = top) from Argus's 7d rank snapshot. Absent when Argus has no rank row for this (project, tag) pair.
    - `share_ratio` number, double: Project's share of total views within this tag over the rank window (0~1). Distinct from `points[].percent` which is the project's own per-tag percentage time-series. Absent when rank data is unavailable.
    - `tag` string, required: Tag / category name, e.g. 'AI', 'DeFi'

## Other responses

- `default`: Error

## Changes

- **2026-10-21** `4f757885d6ff`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/changes/gateway/v1/social/mindshare/get.md)

---

[API](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api.md) - [All operations](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/revisions/91774fdd5302?raw)