Civitai Orchestration

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

Quick Start

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

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

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.

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:

Get oldest workflows first

node civitai-client.js workflows --oldest --take=50

By Tags

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

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:

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:

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

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

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.

node civitai-client.js test

user

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

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.

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.

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 .

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.

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

results

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

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.

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

Environment Variables

Stored in .claude/skills/civitai-orchestration/.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

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

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

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:

node civitai-client.js workflow <workflowId>