kagi summarize

Summarize URLs or text content using either the paid public API or the subscriber web Summarizer.

Synopsis

kagi summarize [OPTIONS]

Description

The kagi summarize command provides access to two different summarization systems:

1. Public API Mode - Uses Kagi's legacy paid Universal Summarizer API (requires KAGI_API_TOKEN)
2. Subscriber Mode - Uses your Kagi subscription's web-based Summarizer (requires KAGI_SESSION_TOKEN)

The two modes have different capabilities, pricing models, and output options. Choose the mode that best fits your use case.

Authentication Modes

Public API Mode (Default)

Requires: KAGI_API_TOKEN

Uses the legacy /api/v0 Universal Summarizer API endpoint with Bot auth. This is a paid service that consumes API credit.

Features:

• Multiple summary engines (cecil, agnes, etc.)
• Caching support
• Structured JSON output
• Consistent API behavior

Cost: Consumes API credit per request

Subscriber Mode

Requires: KAGI_SESSION_TOKEN + --subscriber flag

Uses the subscriber web product's summarization feature. This is included with your Kagi subscription.

Features:

• Multiple summary lengths (headline to long)
• Multiple summary types (summary, keypoints, eli5)
• Translation support
• Web product integration

Cost: Included with subscription (no additional charges)

Options

Content Input (One Required)

--url <URL>

URL of the page to summarize.

Example:

kagi summarize --url https://example.com/article

--text <TEXT>

Raw text to summarize.

Example:

kagi summarize --text "Long text content to summarize..."

Note: Choose either --url or --text, not both.

--filter

Read URLs or text items from stdin, one item per line, and summarize each item. Lines starting with http:// or https:// are sent as URLs; all other lines are sent as text. Prints one compact JSON record per input line in the same order: successful records carry the summary under response, failed records carry an error envelope with "ok": false. Every input is processed even when some fail; the command exits nonzero with an aggregate failure count after all inputs are processed.

cat urls.txt | kagi summarize --filter --subscriber --length digest

Mode Selection

--subscriber

Use subscriber web Summarizer instead of public API.

Requires: KAGI_SESSION_TOKEN

Example:

kagi summarize --subscriber --url https://example.com

Public API Options

--engine <ENGINE>

Summarization engine to use (public API only).

Values:

• cecil - Balanced summarization (default)
• agnes - Alternative engine
• Additional engines as documented

Example:

kagi summarize --url https://example.com --engine cecil

--cache <BOOL>

Enable/disable response caching (public API only).

Values: true, false Default: true

Example:

kagi summarize --url https://example.com --cache false

Subscriber Mode Options

--length <LENGTH>

Summary length (subscriber mode only).

Values:

• headline - Briefest (1-2 sentences)
• overview - Short summary (3-5 sentences)
• digest - Medium length (paragraph)
• medium - Detailed (multiple paragraphs)
• long - Most comprehensive

Example:

kagi summarize --subscriber --url https://example.com --length digest

--summary-type <TYPE>

Style of summary (subscriber mode only).

Values:

• summary - Standard summary
• keypoints - Bullet point key points
• eli5 - Explain Like I'm 5 (simplified)

Example:

kagi summarize --subscriber --url https://example.com --summary-type keypoints

Universal Options

--target-language <LANG>

Target language for summary output.

Example:

kagi summarize --url https://example.com --target-language es

--local-cache

Store and reuse the response in the local cache under ~/.cache/kagi-cli or KAGI_CACHE_DIR.

--cache-ttl <SECONDS>

Override the local cache TTL. Summarize defaults to 3600 seconds when --local-cache is enabled.

Output Format

Public API Output

{
  "meta": {
    "id": "1",
    "node": "us-east",
    "ms": 10
  },
  "data": {
    "output": "The summarized text...",
    "tokens": 42
  }
}

Subscriber Mode Output

{
  "meta": {
    "version": "202603091651.stage.c128588",
    "trace": "abc123"
  },
  "data": {
    "thread_id": "thread-1",
    "state": "done",
    "output": "The summarized text...",
    "markdown": "The summarized text..."
  }
}

Examples

Public API Examples

# Basic URL summarization
kagi summarize --url https://www.rust-lang.org

# With specific engine
kagi summarize --url https://example.com --engine cecil

# Disable caching
kagi summarize --url https://example.com --cache false

# Text summarization
kagi summarize --text "Long text content here..."

Subscriber Mode Examples

# Basic subscriber summarization
kagi summarize --subscriber --url https://www.rust-lang.org

# Key points format
kagi summarize --subscriber --url https://example.com --summary-type keypoints

# Short length
kagi summarize --subscriber --url https://example.com --length overview

# Full options
kagi summarize --subscriber --url https://example.com --summary-type keypoints --length digest --target-language en

Processing Examples

# Extract just the summary text
kagi summarize --url https://example.com | jq -r '.data.output'

# Save to file
kagi summarize --url https://example.com > summary.json

# Batch process URLs
cat urls.txt | while read url; do
  kagi summarize --subscriber --url "$url" > "summaries/$(basename $url).json"
  sleep 1
done

Mode Comparison

Common Patterns

Research Pipeline

#!/bin/bash
# Summarize articles for research

URLS=(
  "https://example.com/article1"
  "https://example.com/article2"
)

for url in "${URLS[@]}"; do
  echo "Processing: $url"
  kagi summarize --subscriber --url "$url" --summary-type keypoints | jq -r '.data.output'
  echo "---"
  sleep 1
done

Quick Reference

# Quick overview of a page
kagi summarize --subscriber --url "$URL" --length overview | jq -r '.data.output'

# Detailed reading
kagi summarize --subscriber --url "$URL" --length long | jq -r '.data.output'

# Key points only
kagi summarize --subscriber --url "$URL" --summary-type keypoints | jq -r '.data.output'

Exit Codes

Common errors:

• Missing required token
• Invalid URL
• Network error
• Rate limiting

Troubleshooting

"this command requires KAGI_API_TOKEN"

You're using public API mode without an API token. Either:

• Set API token: kagi auth set --api-token '...'
• Or use subscriber mode: add --subscriber flag

"this command requires KAGI_SESSION_TOKEN"

You're using --subscriber mode without a session token. Set it:

kagi auth set --session-token 'https://kagi.com/search?token=...'

"--length requires --subscriber"

The --length option only works with subscriber mode:

# Wrong
kagi summarize --url https://example.com --length digest

# Right
kagi summarize --subscriber --url https://example.com --length digest

"--engine is only supported for the paid public summarizer API"

The --engine option only works with public API mode:

# Right (public API)
kagi summarize --url https://example.com --engine cecil

# Wrong (subscriber mode doesn't support engine selection)
kagi summarize --subscriber --url https://example.com --engine cecil

Empty output

• Verify URL is accessible and not blocked
• Check that content is text-based (not just images/video)
• Try different summary type or length

See Also

• Authentication Guide - Token setup
• Workflows - Usage patterns
• Auth Matrix - Command auth requirements