---
title: "Query cards on a dashboard"
method: GET
path: "/v1/projects/{project_id}/dashboards/{id}/cards"
tags: ["Dashboard"]
---

# Query cards on a dashboard

`GET /v1/projects/{project_id}/dashboards/{id}/cards`

## Request

- Base URL: `https://api.telerivet.com`
- URL: `https://api.telerivet.com/v1/projects/{project_id}/dashboards/{id}/cards`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://telerivet.com/oauth/authorize`, token URL `https://api.telerivet.com/oauth/token`)

Queries the cards on this dashboard, in display order, including each card's `config`. Dashboards have at most 20 cards, so all cards are returned in a single page.

## Path parameters

- `project_id` string, required
- `id` string, required

## Query parameters

- `count` boolean

## Response `200`

Successful response. When count=1 parameter is provided, returns {"count": N} instead.

- object
  - `data` DashboardCard[]: Array of results (omitted when count=1)
    - `id` string, nullable: ID of the card (null for an automatically generated card on a dashboard that has not been customized yet; cards receive IDs the first time the dashboard is updated via the API or web app)
    - `type` string: Type of the card: - `messages_chart`: time series chart of messages sent and received - `contacts_chart`: time series chart of the number of contacts - `airtime_chart`: time series chart of airtime transactions - `data_table_chart`: time series chart of the number of rows in data tables - `data_table_summary`: pie or bar chart of the number of rows in a data table by the value of a particular field - `messages`: statistics about messages (e.g. number of messages sent and received today) - `contacts`: statistics about contacts (e.g. number of contacts in particular groups) - `data_tables`: statistics about data tables (e.g. number of rows in particular tables) - `airtime`: statistics about airtime/value transfers - `campaigns`: summary of recent, upcoming, and ongoing campaigns - `campaign_calendar`: calendar of sent and scheduled campaigns - `phones`: list of routes and their current status - `services`: list of active services - `poll`: charts of responses for each question in a poll - `account`: basic account information for the organization - `custom`: custom card with links - `setup`: project setup progress (automatically generated; cannot be added)
    - `title` string: Title of the card. If no title has been set, a default title is displayed based on the card type.
    - `order` integer: Sort order of the card on the dashboard (cards are displayed in ascending order)
    - `width` integer, nullable: Width of the card in pixels, or null if the card has not been resized
    - `height` integer, nullable: Height of the card in pixels, or null if the card has not been resized
    - `config` object: Type-specific configuration parameters for the card. Only returned when retrieving a single card by ID or querying the cards on a dashboard. When updating a card, parameters omitted from `config` keep their current values. **messages card** <th> Parameter </th><th> Description </th> - <code>value_stats</code> - Array of the statistics displayed on the card, in display order. Each item is an object with a <code>type</code> (see below) and, for statistic types that take parameters, a <code>params</code> object. - <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>messages.new</code>, <code>messages.export</code>, <code>messages.stats</code>, <code>custom</code> (see <strong>Links</strong> below). Available `value_stats` types for the `messages` card: <th> Type </th><th> Statistic </th><th> Params </th> - <code>messages.todaycounts</code> - Messages sent and received today by type (expands to multiple statistics, one for each direction/type combination) - - <code>messages.scheduled</code> - Scheduled messages - - <code>messages.scheduledtoday</code> - Messages scheduled for today - - <code>messages.convtoday</code> - Conversations today - - <code>messages.activeconv</code> - Active conversations - - <code>messages.starred</code> - Starred messages - - <code>messages.broadcaststoday</code> - Broadcasts sent today - - <code>messages.status</code> - All messages with a particular status - <code>status</code>: <code>queued</code>, <code>failed</code>, <code>not_delivered</code>, etc. - <code>messages.statustoday</code> - Messages today with a particular status - <code>status</code>: <code>failed</code>, <code>not_delivered</code>, <code>service_error</code>, etc. - <code>messages.labelcount</code> - Messages with a particular label - <code>label_id</code>: ID of the label **contacts card** <th> Parameter </th><th> Description </th> - <code>value_stats</code> - Array of the statistics displayed on the card, in display order. Each item is an object with a <code>type</code> (see below) and, for statistic types that take parameters, a <code>params</code> object. - <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>contacts.add</code>, <code>contacts.import</code>, <code>contacts.export</code>, <code>custom</code> (see <strong>Links</strong> below). Available `value_stats` types for the `contacts` card: <th> Type </th><th> Statistic </th><th> Params </th> - <code>contacts.total</code> - Total number of contacts - - <code>contacts.incomingtoday</code> - Contacts heard from today - - <code>contacts.outgoingtoday</code> - Contacts contacted today - - <code>contacts.createdtoday</code> - Contacts created today - - <code>contacts.groupmembers</code> - Contacts in a particular group - <code>group_id</code>: ID of the group - <code>contacts.viewcount</code> - Contacts matching custom filters - <code>title</code>: displayed title; <code>filters</code>: object of conditions that contacts must match, in the same format as the <code>filters</code> of a dynamic group (see [project.createGroup](#Project.createGroup)) **data_tables card** <th> Parameter </th><th> Description </th> - <code>value_stats</code> - Array of the statistics displayed on the card, in display order. Each item is an object with a <code>type</code> (see below) and, for statistic types that take parameters, a <code>params</code> object. - <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>datatables.add</code>, <code>custom</code> (see <strong>Links</strong> below). Available `value_stats` types for the `data_tables` card: <th> Type </th><th> Statistic </th><th> Params </th> - <code>tables.recentlyupdated</code> - Rows in recently updated data tables (expands to multiple statistics, one for each of the 5 most recently-updated data tables) - - <code>tables.rows</code> - Rows in a particular data table - <code>table_id</code>: ID of the data table - <code>tables.viewrows</code> - Rows in a particular data table view - <code>view_id</code>: ID of the data table view; <code>title</code>: displayed title **airtime card** <th> Parameter </th><th> Description </th> - <code>value_stats</code> - Array of the statistics displayed on the card, in display order. Each item is an object with a <code>type</code> (see below) and, for statistic types that take parameters, a <code>params</code> object. - <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>airtime.send</code>, <code>airtime.stats</code>, <code>custom</code> (see <strong>Links</strong> below). Available `value_stats` types for the `airtime` card: <th> Type </th><th> Statistic </th><th> Params </th> - <code>airtime.txtoday</code> - Airtime transactions today - - <code>airtime.spenttoday</code> - Airtime spent today - - <code>airtime.balance</code> - Current balance with airtime providers - **messages_chart card** <th> Parameter </th><th> Description </th> - <code>statistic</code> - Value to chart: <code>count</code> (number of messages), <code>num_parts</code> (number of SMS parts), <code>duration</code> (call duration), or <code>price.&lt;currency&gt;</code> (total price of messages in a particular currency, e.g. <code>price.USD</code>, where <code>&lt;currency&gt;</code> is a 3-letter ISO currency code in which messages in the project have been priced) - <code>group_ids</code> - Array of series group IDs determining how messages are grouped into chart series: <code>type</code>, <code>direction</code>, <code>status</code>, <code>source</code>, <code>simulated</code>, <code>gateway</code>, <code>network</code>, <code>currency</code>, <code>link</code>, <code>user</code>, <code>phone</code>, <code>service</code> - <code>filters</code> - Object of filter conditions on the messages included in the chart, e.g. <code>{"dir": "incoming", "type": "sms"}</code>. Each key is the filter parameter for a group that must be included in <code>group_ids</code>: <code>type</code> (message type, e.g. <code>sms</code>, <code>call</code>), <code>dir</code> (<code>incoming</code> or <code>outgoing</code>), <code>status</code> (message status, e.g. <code>sent</code>, <code>delivered</code>, <code>failed</code>), <code>source</code> (e.g. <code>phone</code>, <code>web</code>, <code>api</code>, <code>service</code>), <code>simulated</code> (bool), <code>gateway</code> (gateway ID), <code>mccmnc</code> (mobile network code), <code>currency</code>, <code>link</code> (<code>clicked</code>, <code>not_clicked</code>, or <code>no_link</code>), <code>user</code>, <code>phone</code>, <code>service</code> (IDs). Each value is a single value or an array of values to match. - <code>rollup</code> - Time period per data point: <code>day</code>, <code>week</code>, <code>month</code>, or <code>year</code> - <code>date_range_mode</code> - <code>recent</code> (the most recent <code>prev_days</code> days) or <code>fixed</code> (from <code>start_date</code> to <code>end_date</code>) - <code>prev_days</code> - Number of days to display when <code>date_range_mode</code> is <code>recent</code> (int) - <code>start_date</code> - First date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code> - <code>end_date</code> - Last date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code> - <code>cumulative</code> - If true, each data point shows the cumulative total up to that date (bool) **airtime_chart card** <th> Parameter </th><th> Description </th> - <code>statistic</code> - Value to chart: <code>count</code> (number of successful transactions), <code>topup_value.&lt;currency&gt;</code> (total value transferred, e.g. <code>topup_value.KES</code>), or <code>price.&lt;currency&gt;</code> (total price of transactions, e.g. <code>price.USD</code>), where <code>&lt;currency&gt;</code> is a 3-letter ISO currency code in which transactions in the project have been valued or priced - <code>group_ids</code> - Array of series group IDs: <code>airtime.billing</code>, <code>airtime.status</code>, <code>airtime.country</code>, <code>airtime.productid</code>, <code>airtime.category</code> - <code>filters</code> - Object of filter conditions on the transactions included in the chart. Each key is the filter parameter for a group that must be included in <code>group_ids</code>: <code>internal_billing</code> (bool), <code>status</code> (e.g. <code>successful</code>, <code>failed</code>, <code>cancelled</code>), <code>country</code> (country code), <code>product_id</code>, <code>provider_category</code>. Each value is a single value or an array of values to match. - <code>rollup</code> - Time period per data point: <code>day</code>, <code>week</code>, <code>month</code>, or <code>year</code> - <code>date_range_mode</code> - <code>recent</code> (the most recent <code>prev_days</code> days) or <code>fixed</code> (from <code>start_date</code> to <code>end_date</code>) - <code>prev_days</code> - Number of days to display when <code>date_range_mode</code> is <code>recent</code> (int) - <code>start_date</code> - First date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code> - <code>end_date</code> - Last date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code> - <code>cumulative</code> - If true, each data point shows the cumulative total up to that date (bool) **contacts_chart card** <th> Parameter </th><th> Description </th> - <code>series</code> - Array of up to 10 data series to chart (the same keys as the <code>series</code> parameter of [project.getContactStats](#Project.getContactStats)): each item is either <code>total</code> (the total number of contacts in the project) or the ID of a contact group (the number of contacts in that group) - <code>rollup</code> - Time period per data point: <code>day</code>, <code>week</code>, <code>month</code>, or <code>year</code> - <code>date_range_mode</code> - <code>recent</code> (the most recent <code>prev_days</code> days) or <code>fixed</code> (from <code>start_date</code> to <code>end_date</code>) - <code>prev_days</code> - Number of days to display when <code>date_range_mode</code> is <code>recent</code> (int) - <code>start_date</code> - First date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code> - <code>end_date</code> - Last date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code> - <code>cumulative</code> - If true, each data point shows the cumulative total up to that date (bool) **data_table_chart card** <th> Parameter </th><th> Description </th> - <code>series</code> - Array of up to 10 data series to chart (the same keys as the <code>series</code> parameter of [project.getDataTableStats](#Project.getDataTableStats)): each item is the ID of a data table or data table view (the number of rows in that table or view) - <code>rollup</code> - Time period per data point: <code>day</code>, <code>week</code>, <code>month</code>, or <code>year</code> - <code>date_range_mode</code> - <code>recent</code> (the most recent <code>prev_days</code> days) or <code>fixed</code> (from <code>start_date</code> to <code>end_date</code>) - <code>prev_days</code> - Number of days to display when <code>date_range_mode</code> is <code>recent</code> (int) - <code>start_date</code> - First date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code> - <code>end_date</code> - Last date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code> - <code>cumulative</code> - If true, each data point shows the cumulative total up to that date (bool) **data_table_summary card** <th> Parameter </th><th> Description </th> - <code>table_id</code> - ID of the data table - <code>stats_variable</code> - The custom variable (field) of the data table to count rows by, e.g. <code>region</code> (without the <code>vars.</code> prefix used in <code>filters</code>) - <code>chart_type</code> - <code>pie</code> or <code>bar</code> - <code>sort</code> - Sort order of the values: <code>count</code> (by number of rows) or <code>value</code> - <code>num_values</code> - Maximum number of values to display (int) - <code>filters</code> - Object of conditions that rows must match to be counted. To filter by a custom variable (field) of the table, precede the field name with <code>vars.</code> (e.g. <code>{"vars.region": "North"}</code>); other supported keys are <code>view</code> (ID of a data table view whose rows should be counted), <code>id</code>, <code>contact_id</code>, <code>contact_name</code>, <code>from_number</code>, <code>time_created</code>, and <code>time_updated</code>. Each value is either a value to match exactly, or an object with an operator such as <code>ne</code>, <code>prefix</code>, <code>gte</code>, <code>lt</code>, <code>exists</code>, or <code>not_exists</code> as the key (e.g. <code>{"vars.age": {"gte": 18}}</code>). **poll card** <th> Parameter </th><th> Description </th> - <code>service_id</code> - ID of the poll service - <code>chart_type</code> - <code>pie</code>, <code>bar</code>, or <code>none</code> **campaign_calendar card** <th> Parameter </th><th> Description </th> - <code>period</code> - <code>month</code>, <code>week</code>, or <code>day</code> - <code>status</code> - Only display campaigns with this status: <code>draft</code>, <code>scheduled</code>, <code>sent</code>, or <code>pending_review</code> (null to display all campaigns) **campaigns card** <th> Parameter </th><th> Description </th> - <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>campaigns.new</code>, <code>custom</code> (see <strong>Links</strong> below). **services card** <th> Parameter </th><th> Description </th> - <code>filters</code> - Object of filter conditions for the services displayed on the card: <code>trigger</code> (<code>incoming_message</code>, <code>manual</code>, <code>recurring</code>, <code>message_action</code>, <code>contact_action</code>, <code>outgoing_call</code>, <code>message_status</code>, <code>link</code>, <code>data_row_action</code>, <code>project_action</code>, or <code>webhook</code>), <code>template</code> (bool; if true, only display custom templates), <code>tag</code> (only display services with this tag) - <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>services.add</code>, <code>custom</code> (see <strong>Links</strong> below). **phones card** <th> Parameter </th><th> Description </th> - <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>phones.add</code>, <code>phones.routes</code>, <code>custom</code> (see <strong>Links</strong> below). **account card** <th> Parameter </th><th> Description </th> - <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>account.billing</code>, <code>account.users</code>, <code>account.api</code>, <code>custom</code> (see <strong>Links</strong> below). **custom card** <th> Parameter </th><th> Description </th> - <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>custom</code> (see <strong>Links</strong> below). **Links** Link types other than `custom` take no parameters. A `custom` link has the following `params`: <th> Param </th><th> Description </th> - <code>title</code> - Displayed link text - <code>link_type</code> - Determines how <code>url_suffix</code> is interpreted: <code>project_relative</code> (default), <code>account_relative</code>, <code>user_relative</code>, or <code>external</code> (see below) - <code>url_suffix</code> - The link destination, whose format depends on <code>link_type</code>:<br /> - <code>project_relative</code>: a path relative to the project's URL in the Telerivet web app (e.g. <code>messages</code> or <code>contacts?f[group]=CG2ad0100821a98bea</code> links to <code>https://telerivet.com/p/&lt;project url_slug&gt;/messages</code> or <code>.../contacts?...</code>)<br /> - <code>account_relative</code>: a path relative to the organization's URL in the web app (<code>https://telerivet.com/a/&lt;organization id&gt;/</code>), e.g. <code>billing</code><br /> - <code>user_relative</code>: a path relative to the URL of the user viewing the dashboard (<code>https://telerivet.com/u/&lt;username&gt;/</code>), e.g. <code>settings</code><br /> - <code>external</code>: an absolute URL, e.g. <code>https://example.com/report</code> - <code>open_in_new_tab</code> - If true, the link opens in a new browser tab (bool)
    - `dashboard_id` string: ID of the dashboard this card belongs to
    - `project_id` string: ID of the project this card belongs to
    - `time_created` integer, nullable: Time the card was created in Telerivet (null for an automatically generated card on a dashboard that has not been customized)
    - `time_updated` integer, nullable: Time the card was last updated in Telerivet
  - `truncated` boolean: True if there are more results
  - `next_marker` string: Marker for pagination
  - `page_size` integer: Number of results per page
  - `sort_dir` 'asc' | 'desc': Sort direction
  - `count` integer: Total count of matching items (only when count=1 parameter is provided)

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key or Bearer token
- `404`: Resource not found

---

[API](https://skmtc.dev/telerivet/apis/telerivet-api.md) · [All operations](https://skmtc.dev/telerivet/apis/telerivet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/telerivet/apis/telerivet-api/revisions/4e14b1c8d917?raw)