voluum-command-composer

voluum-cli is community-supported software released under the MIT License. It is not an official Voluum product and is not endorsed or supported by Voluum. It uses publicly documented Voluum APIs.

What this skill does

• Translates user intent into concrete voluum commands.
• Builds reporting queries (summary, breakdown, query, schema, raw) with correct flags.
• Provides troubleshooting for auth and API request errors.

Rules

• Never ask users to paste raw secrets into chat.
• Never output full tokens; mask values in examples.
• Prefer environment variables and stored config over inline secrets.
• Validate required fields before giving final commands.

Auth

# Access key login (preferred — longer-lived than email/password sessions)
voluum auth login --accessKeyId '<KEY_ID>' --accessKey '<ACCESS_KEY>'

# Email/password login
voluum auth login --email you@example.com --password '<PASSWORD>'

# Check current token
voluum auth whoami

Set env vars in ~/.zshrc or ~/.bashrc to avoid re-logging in:

export VOLUUM_BASE_URL=https://api.voluum.com
export VOLUUM_TOKEN=<your-token>

Campaigns

voluum campaigns list
voluum campaigns get --id '<CAMPAIGN_ID>'

Reports — Key Patterns

Sorting (IMPORTANT)

The Voluum API uses two separate params for sorting. The combined sort=field:direction syntax does NOT work and returns a 400 error.

Correct:

sort=revenue    direction=desc
sort=visits     direction=asc
sort=conversions direction=desc

Wrong (will 400):

sort=revenue:desc   ← invalid

--query vs --query-json

• --query parses comma-separated key=value pairs: good for simple params
• --query-json accepts a JSON object: required when a value contains commas (e.g. columns=a,b,c)
• They merge; --query-json wins on duplicate keys

Example combining both:

voluum reports query \
  --query "from=2026-02-01T00:00:00.000Z,to=2026-02-18T00:00:00.000Z,groupBy=campaignId,limit=20" \
  --query-json '{"sort":"revenue","direction":"desc","columns":"campaignId,campaignName,revenue,conversions,cr,epc"}'

Output size

• Large requests (200+ rows, wide columns list) can produce 50KB+ responses.
• Use --out <file> to capture full output: stdout is capped at ~24k chars.
• Strip noise: output already omits columnMappings and internal metadata fields.

Report Commands

Summary (top-level totals + groupBy)

# 7-day campaign summary
voluum reports summary \
  --from 2026-02-12T00:00:00.000Z \
  --to   2026-02-19T00:00:00.000Z \
  --groupBy campaign

Query (flexible — use for sorting, custom columns, pagination)

# Top 20 campaigns by revenue
voluum reports query \
  --query-json '{
    "from":      "2026-02-12T00:00:00.000Z",
    "to":        "2026-02-19T00:00:00.000Z",
    "groupBy":   "campaignId",
    "limit":     20,
    "sort":      "revenue",
    "direction": "desc",
    "columns":   "campaignId,campaignName,revenue,conversions,cr,epc,ap"
  }'

# Top 20 offers by revenue
voluum reports query \
  --query-json '{
    "from":      "2026-02-12T00:00:00.000Z",
    "to":        "2026-02-19T00:00:00.000Z",
    "groupBy":   "offerId",
    "limit":     20,
    "sort":      "revenue",
    "direction": "desc",
    "columns":   "offerId,offerName,revenue,conversions,cr,epc,ap"
  }'

# Save large results to file
voluum reports query \
  --query-json '{"from":"...","to":"...","groupBy":"campaignId","limit":200,"sort":"revenue","direction":"desc"}' \
  --out /tmp/campaigns.json

Breakdown (presets: offer | offer-by-campaign | flow | traffic-source | lander)

# Traffic source distribution
voluum reports breakdown --by traffic-source \
  --from 2026-02-12T00:00:00.000Z \
  --to   2026-02-19T00:00:00.000Z \
  --limit 50

# Offer breakdown for a specific campaign
voluum reports breakdown --by offer-by-campaign \
  --campaignId '<CAMPAIGN_ID>' \
  --from 2026-02-12T00:00:00.000Z \
  --to   2026-02-19T00:00:00.000Z

# Lander performance
voluum reports breakdown --by lander \
  --from 2026-02-12T00:00:00.000Z \
  --to   2026-02-19T00:00:00.000Z \
  --limit 20

# Flow breakdown
voluum reports breakdown --by flow \
  --from 2026-02-12T00:00:00.000Z \
  --to   2026-02-19T00:00:00.000Z

Schema discovery

# List all groupable columns for a report
voluum reports schema \
  --query "from=2026-02-01T00:00:00.000Z,to=2026-02-18T00:00:00.000Z,groupBy=campaignId" \
  --groupable

# Find money columns with search
voluum reports schema \
  --query "from=2026-02-01T00:00:00.000Z,to=2026-02-18T00:00:00.000Z,groupBy=campaignId" \
  --type money --search revenue

# Full param catalog
voluum reports schema \
  --query "from=2026-02-01T00:00:00.000Z,to=2026-02-18T00:00:00.000Z,groupBy=campaignId" \
  --with-query-params

Raw conversions

voluum reports raw \
  --from 2026-02-12T00:00:00.000Z \
  --to   2026-02-19T00:00:00.000Z \
  --limit 50

Useful groupBy values

Note: country is not a valid groupBy for /report. Use /report/conversions or check voluum reports schema --groupable for valid groupBy fields per endpoint.

Sortable fields (common)

revenue, visits, conversions, clicks, cr, epc, ap, profit, roi, cv

Always pair with direction=asc or direction=desc.

Passthrough API

voluum api get /campaign --query status=active,limit=50
voluum api get /traffic-source

Error handling

Notes from production use

• Filters like trafficSourceId=<id> in the query are accepted but may be silently ignored by some report endpoints — verify by checking if totalRows changes.
• The columns=... param is accepted but Voluum returns all fields anyway; it’s cosmetic.
• Default output is TOON (Token-Oriented Object Notation) — compact, 30-60% fewer tokens than JSON. Use --json for compact JSON or --pretty for pretty-printed JSON.
• --json is required when piping to jq or other JSON tools.
• --out <file> always writes full output regardless of format.