Agent skill

civitai-orchestration

Query and explore Civitai Orchestration workflows, jobs, and results. Use for analyzing image/video generation jobs, viewing job results, searching by workflow ID, job ID, user, or date range.

View SKILL.md on GitHub Repository
Stars 7,065
Forks 713

Install this agent skill to your Project

npx add-skill https://github.com/civitai/civitai/tree/main/.claude/skills/civitai-orchestration

SKILL.md

Civitai Orchestration

Interact with the Civitai Orchestration API to query workflows, view job details, and retrieve generation results.

Quick Start

bash
# Query workflows for a specific user
node .claude/skills/civitai-orchestration/civitai-client.js user 12345

# Get a specific workflow by ID
node .claude/skills/civitai-orchestration/civitai-client.js workflow <workflowId>

# Get job details with scan results (hive_csam_score, etc.)
node .claude/skills/civitai-orchestration/civitai-client.js job <jobId>

# Get step details from a workflow
node .claude/skills/civitai-orchestration/civitai-client.js step <workflowId> <stepName>

# Download result images/videos from a workflow
node .claude/skills/civitai-orchestration/civitai-client.js results <workflowId>

Searching & Filtering

By User ID

bash
# Get workflows for user 12345
node civitai-client.js user 12345

# With options
node civitai-client.js user 12345 --take=5 --excludeFailed

By Workflow ID

bash
# Direct lookup by workflow ID
node civitai-client.js workflow 0-019be44b-181e-7a7e-ab1b-b58dc7610dca

By Date Range

Note: Date filtering may have limited functionality depending on API access level.

bash
# Workflows from the last 7 days
node civitai-client.js workflows --from=2024-01-15 --to=2024-01-22

# Workflows from a specific day
node civitai-client.js workflows --from=2024-01-20 --to=2024-01-20

# Dates are assumed to be UTC. Add Z suffix for explicit UTC:
node civitai-client.js workflows --from=2024-01-20T06:00:00Z --to=2024-01-20T12:00:00Z

Alternative: Use --oldest to get workflows from oldest first, then paginate:

bash
# Get oldest workflows first
node civitai-client.js workflows --oldest --take=50

By Tags

Tags are set when workflows are created. Common tag patterns:

bash
# Filter by a specific tag
node civitai-client.js workflows --tag=user:12345

# Note: Multiple tags can be specified (AND logic)
node civitai-client.js workflows --tag=project:myproject --tag=type:image

By Metadata Search

The --query option searches workflow metadata:

bash
# Search metadata for a string
node civitai-client.js workflows --query="portrait"

By Status

The API supports excluding failed workflows but not filtering by specific status:

bash
# Exclude failed/canceled workflows (get only succeeded/processing)
node civitai-client.js workflows --excludeFailed

# Include all statuses (default behavior)
node civitai-client.js workflows

Note: To find specific statuses, retrieve workflows and filter client-side, or use metadata/tags when creating workflows for better filtering.

Pagination

bash
# Get 50 results
node civitai-client.js workflows --take=50

# Get next page using cursor from previous response
node civitai-client.js workflows --take=20 --cursor=<nextCursor>

Combined Filters

bash
# Successful workflows for a specific tag, excluding failures
node civitai-client.js workflows \
  --tag=user:12345 \
  --excludeFailed \
  --take=50

# Get workflows with metadata search
node civitai-client.js workflows \
  --query="portrait" \
  --excludeFailed \
  --take=20

Commands Reference

test

Test API connection and verify credentials.

bash
node civitai-client.js test

user

Query workflows for a specific user by their Civitai user ID.

bash
node civitai-client.js user <userId> [options]

Options:

Option Description
--take=<n> Number of results (max 10 per API limit)
--tag=<tag> Filter by tag
--query=<text> Search workflow metadata
--excludeFailed Exclude failed/canceled workflows
--oldest Sort from oldest to newest

workflows

List and search workflows with optional filters.

bash
node civitai-client.js workflows [options]

Options:

Option Description
--tag=<tag> Filter by tag (can specify multiple)
--query=<text> Search workflow metadata
--excludeFailed Exclude failed/canceled workflows
--oldest Sort from oldest to newest
--take=<n> Number of results (default: 20)
--cursor=<cursor> Pagination cursor
--from=<date> Start date (may have limited support)
--to=<date> End date (may have limited support)

workflow

Get details of a specific workflow.

bash
node civitai-client.js workflow <workflowId> [--wait]

Options:

Option Description
--wait Wait/poll for completion (with timeout)

job

Get details of a specific job including scan results from event context.

This is useful for investigating content moderation results - the lastEvent.context contains scan scores like hive_csam_score and hive_vlm_summary.

bash
node civitai-client.js job <jobId> [--raw]

Options:

Option Description
--raw Output raw JSON instead of formatted summary

Example output:

Job Summary:
  ID: 58de87d7-d594-4d71-ae43-dd8fc1bcbd23
  Type: TextToImageV2
  Workflow ID: 8484131-20260121222126332

Prompt Classification: sexual, young, scan

Results (2 blob(s)):
  - JNFDW54JNTATNW42HACYCWSQP0.jpeg (available: true)

Last Event:
  Type: Succeeded
  Provider: ValdiAI

Event Context (scan results, metrics):
  ** hive_csam_score: 0.00 %, 0.00 %
  ** hive_vlm_summary: X, No_Child

step

Get details of a specific step within a workflow.

bash
node civitai-client.js step <workflowId> <stepName>

results

Download or view results (images/videos) from a workflow.

bash
node civitai-client.js results <workflowId> [--download] [--dir=<path>]

Options:

Option Description
--download Download result files
--dir=<path> Download directory (default: ./civitai-downloads)

blob

Get a blob (image/video) by ID with optional NSFW handling.

bash
node civitai-client.js blob <blobId> [--download] [--nsfw]

Environment Variables

Stored in .claude/skills/civitai-orchestration/.env:

env
CIVITAI_API_TOKEN=your_bearer_token
CIVITAI_API_URL=https://orchestration-new.civitai.com

API Reference

Workflow Query Parameters

The workflows endpoint supports these query parameters:

  • tags - Array of tags to filter by
  • query - Search workflow metadata
  • fromDate / toDate - Date range (ISO 8601) - may have limited support
  • cursor - Pagination cursor
  • take - Number of results (default: 100)
  • excludeFailed - Exclude failed/expired/canceled workflows (boolean)
  • ascending - Sort oldest to newest (boolean)

Workflow Statuses

Status Description
preparing Workflow being prepared
scheduled Scheduled for execution
processing Currently running
succeeded Completed successfully
failed Failed with error
canceled Was canceled
expired Timed out
deleted Deleted

Step Types (Recipes)

Image/Video generation steps you might encounter:

  • textToImage - Text to image generation
  • imageGen - General image generation
  • videoGen - Video generation
  • videoEnhancement - Video upscaling/enhancement
  • videoFrameExtraction - Extract frames from video
  • videoUpscaler - Upscale video
  • videoInterpolation - Frame interpolation
  • convertImage - Convert image formats
  • comfy - ComfyUI workflow execution

Examples

Query a user's recent image generations

bash
# Get user 12345's recent workflows
node civitai-client.js user 12345

# Exclude failed jobs
node civitai-client.js user 12345 --excludeFailed

Get workflow and view results

bash
# Get workflow details
node civitai-client.js workflow abc123-def456

# View/download results
node civitai-client.js results abc123-def456 --download --dir=./my-images

Paginate through workflows

bash
# First page
node civitai-client.js workflows --take=10

# Next page (use cursor from previous response)
node civitai-client.js workflows --take=10 --cursor=<nextCursor>

Error Handling

Error Code Meaning
401 Invalid or expired token - check CIVITAI_API_TOKEN
404 Workflow/Job not found
429 Rate limited - wait before retrying
422 Invalid parameters

Output

The user command displays workflow summaries including:

  • Workflow ID, status, timestamps
  • Step types (textToImage, videoGen, comfy, etc.)
  • Prompts for text-to-image generations

For raw JSON output, use the workflow command:

bash
node civitai-client.js workflow <workflowId>

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

civitai/civitai

clickhouse-query

Run ClickHouse queries for analytics, metrics analysis, and event data exploration. Use when you need to query ClickHouse directly, analyze metrics, check event tracking data, or test query performance. Read-only by default.

7,065 713
Explore
civitai/civitai

redis-inspect

Inspect Redis cache keys, values, and TTLs for debugging. Supports both main cache and system cache. Use for debugging cache issues, checking cached values, and monitoring cache state. Read-only by default.

7,065 713
Explore
civitai/civitai

quick-mockups

Create multiple UI design mockups in parallel. Use when asked to create mockups, wireframes, or design variations for a feature. Creates HTML files using Mantine v7 + Tailwind following Civitai's design system.

7,065 713
Explore
civitai/civitai

flipt

Manage Flipt feature flags - list, create, enable/disable, and configure rollout rules. Use when you need to control feature flag state or set up segmented rollouts.

7,065 713
Explore
civitai/civitai

bitdex-test

7,065 713
Explore
civitai/civitai

metabase

Create and manage Metabase questions, dashboards, and public links. Use when the user wants to build metrics dashboards, create saved questions with SQL queries, or share analytics publicly.

7,065 713
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results