Group

Group provides detailed information about an AI generation group — the collection of model calls (runs) and messages produced during a training interaction. This is the deepest level of inspection for understanding exactly what the AI generated and how it was used.

Group is a view on the system artifact, exposed via two endpoints:

• POST /system/group — single group detail (lean resolve or full detail tree depending on include_detail in the body).
• POST /system/groups — paginated list of all groups (also surfaces cost / pricing data; this is what powers the Pricing page’s group-history table).

The CLI surfaces these as glow system group and glow system groups.

What is Group?

When a TA interacts with a student persona simulation, Glow creates a group that tracks all AI model runs and messages in that interaction. A group contains:

• Multiple runs, each representing a single AI model invocation with input/output token counts and cost
• Messages within each run, organized by role (system, user, assistant) with support for text, audio, image, video, and file uploads
• Tool calls made during the interaction
• Metadata about which models, agents, and profiles participated

Groups are essential for debugging AI behavior, auditing training interactions for academic integrity, reviewing FERPA-sensitive conversations, and understanding token consumption patterns.

Quick Start

CLI

Calls below use $GLOW_INSTANCE_URL + $GLOW_TOKEN — see Authentication to export them once.

# Lean resolve — group identity only (cheap path used by audit linking)
glow system group --body '{"group_id": "group-uuid"}'
 
# Full detail tree with all runs + messages
glow system group --body '{"group_id": "group-uuid", "include_detail": true, "message_limit": 50}'
 
# Paginate all groups (used by Pricing's group-history table)
glow system groups --body '{"page_size": 25}'
 
# Export group data as a ZIP
glow system export --body '{"target_group_id": "group-uuid"}'

API

# Get one group (set include_detail for the full tree)
curl -X POST $GLOW_INSTANCE_URL/system/group \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "group-uuid",
    "include_detail": true,
    "message_limit": 100,
    "message_offset": 0
  }'
 
# List groups (pricing / cost view)
curl -X POST $GLOW_INSTANCE_URL/system/groups \
  -H "Authorization: Bearer $GLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 20}'

Lean vs. detail

Request fields

Understanding the detail response

The full-detail response (include_detail=true) includes:

• group_exists — Whether the group was found.
• actor_name — Display name of the current user.
• group_name — Display name of the group.
• total_message_count — Total messages in the group (for pagination).

Runs

The runs array contains GroupDetailRunWithMessages objects:

Each run has:

• run — Run metadata:
  • id — UUID of the run
  • created_at — Timestamp
  • input_tokens, output_tokens, cached_input_tokens — Token counts
  • cost — Dollar cost of this run
  • model_id — Which AI model was used
  • agent_id — Which agent processed the run
  • profile_id — Which user triggered the run
• messages — Array of GroupDetailMessageItem objects:
  • id — UUID
  • role — Message role (system, user, assistant)
  • text_upload_ids — UUIDs for text content
  • audio_upload_ids, image_upload_ids, video_upload_ids, file_upload_ids — Media upload UUIDs
  • calls — Tool/function calls made, each with id, template_name, file_path, created_at
• previous_context_start_index — Where previous context starts in the message array (for understanding context windows)

Resources

• models — Models used, each with model_id and name.
• agents — Agents used, each with agent_id and name.
• profiles — Profiles involved, each with profile_id and name.

Downloading media

Messages reference uploaded media via their *_upload_ids fields. The canonical download path is the system artifact’s media endpoints:

Each takes the relevant <kind>_upload_id in the body and supports range requests for large files.

Listing groups

AI generation flow

Groups are created as part of the AI generation flow, which produces stream events (delivered over SSE via POST /<artifact>/watch):

1. GenerationProgressEvent — Reports completed_resources / total_resources and percentage.
2. GenerationCompleteEvent — Indicates success or failure for an artifact_type.
3. GenerationSavedEvent — Confirms the artifact was saved.
4. GenerationErrorEvent — Reports errors with message details.
5. GenerationMediaProgressEvent / GenerationMediaCompleteEvent — Track image/video generation.

Each event references the group_id and run_id.

Common Operations

Related

• System API Reference — every system/* endpoint
• System CLI Reference — every glow system ... command
• Session — session-level view that lists groups
• Pricing — aggregated cost view across all groups
• Invocation — AI model call tracking inside tests