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

# upstack query-channel-details

> List ad accounts, campaigns, ad sets, or ads with optional metrics from the command line. Wraps POST /api/query-channel-details.

List ad accounts, campaigns, ad sets, or ads — with optional metric
aggregation — from the ads-platform integrations connected to your pixel.
Wraps `POST /api/query-channel-details` — see the
[API reference](/api-reference/overview).

The **grain** is controlled by `--dimensions`:

* omit it for **account grain** (the default; one row per ad account across
  every connected platform — Facebook, Google, TikTok),
* pass exactly one of `campaign`, `adset`, or `ad` for that grain.

When `--date-start` / `--date-end` are omitted, the response is an
entity-only listing (no metric aggregation). To scope by ad platform, use a
canonical filter on `channel.resource_source` (not a dimension).

## Usage

```bash theme={null}
upstack query-channel-details --granularity day
```

## Required flags

| Flag                | Description                                |
| ------------------- | ------------------------------------------ |
| `--granularity <g>` | `hour`, `day`, `week`, `month`, or `year`. |

## Optional flags

| Flag                                                  | Description                                                                            | Default           |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------- |
| `--dimensions <grain>`                                | `campaign`, `adset`, or `ad`. Omit for account grain.                                  | (account)         |
| `--date-start <YYYY-MM-DD>` `--date-end <YYYY-MM-DD>` | Date range. Required together with `--measures` (entity-list-only when absent).        |                   |
| `--measures <m1,m2,...>`                              | Comma-separated measure ids (e.g. `channel.spend`, `channel.impressions`, `meta.cpm`). |                   |
| `--filter <json>`                                     | Canonical [Filter](/cli/filters) as JSON.                                              |                   |
| `--timezone <tz>`                                     | IANA timezone.                                                                         | `UTC`             |
| `--limit <n>`                                         | Max rows returned (1–500).                                                             | `50`              |
| `--offset <n>`                                        | Skip the first N rows.                                                                 | `0`               |
| `--sort-by <field>`                                   | One of `sourceUpdatedAt`, `sourceCreatedAt`, `resourceName`.                           | `sourceUpdatedAt` |
| `--sort-direction <dir>`                              | `asc` or `desc` (case-insensitive).                                                    | `desc`            |

See [`upstack query`](/cli/query#shared-flags) for the shared output /
from-file flags.

## Examples

```bash theme={null}
# Top 50 ad accounts across all connected platforms (listing-only)
upstack query-channel-details --granularity day

# Campaigns with spend + impressions for April
upstack query-channel-details \
  --dimensions campaign \
  --granularity day \
  --date-start 2026-04-01 --date-end 2026-04-30 \
  --measures channel.spend,channel.impressions

# Scope to one Facebook ad account via canonical filter
upstack query-channel-details \
  --dimensions campaign --granularity day \
  --filter '{"and":[{"field":"channel.account_id","op":"equals","value":"<account_id>"}]}'

# Drill from a specific campaign down to its ad sets
upstack query-channel-details \
  --dimensions adset --granularity day \
  --filter '{"and":[{"field":"channel.campaign_id","op":"equals","value":"<campaign_id>"}]}'
```

## See also

* [`upstack filters`](/cli/filters) — discover valid filter fields, operators,
  and applicable contexts (every `channel.*` field is valid here).
* [`upstack measures`](/cli/measures) — list measure ids available across all
  query endpoints.