Create Thread - Task Framework

Threads Create Thread

Create New Thread

Configure and execute a new task thread

About Thread Creation

Threads represent task execution instances. Choose async mode for long-running tasks (returns immediately) or sync mode to wait for completion. Your configured user_id and app_id will be automatically included in the metadata.

API Headers

Authentication and filtering headers (auto-populated from Settings)

X-API-Key *

Required for API authentication

X-User-ID

Optional user identifier for filtering

X-App-ID

Optional application identifier for filtering

Target Environment

The environment this thread will run in. Task versions are filtered to those activated in the selected environment.

Environment *

Defaults to the environment selected in the sidebar. Change the environment to see task versions activated there.

Task Selection

Select the task definition to execute

Task *

Choose the task definition to run

Thread Configuration

Execution Mode *

Async: Returns immediately with 202 Accepted. Use for long-running tasks.
Sync: Waits for task completion and returns 201 Created. Use for quick tasks.

Thread Name

Optional name for identifying and searching threads.

Input Artifacts *

At least one input artifact is required. Available types are determined by the task configuration.

Artifact #1

Kind *

Reference (optional)

Stable reference name (unique within thread)

Text Content *

Media Type (optional)

Description (optional)

Task Parameters (Optional)

Parameters (JSON)

Optional task-specific parameters as valid JSON. These are passed directly to your task function.

Metadata (Optional)

Custom Metadata (JSON)

Optional additional metadata as valid JSON. The user_id and app_id from your settings will be automatically added to the metadata.

Execution Timeout (seconds)

Optional execution timeout in seconds (minimum: 1). If the thread doesn't complete within this time, it will be marked as timeout.

Idempotency Key

Optional key to prevent duplicate thread creation. If a thread with the same key exists, the API will return 409 Conflict with the existing thread.

Webhook Callbacks

Optional webhook URLs to receive notifications when thread state changes.

Cancel

💡 Tips

Use async mode for tasks that take more than a few seconds
At least one input artifact is required - add text, JSON, or URL inputs
Use params for task-specific configuration (model settings, thresholds, etc.)
Add custom metadata to organize and filter threads
Set a timeout to prevent threads from running indefinitely
Use idempotency keys to prevent accidental duplicate submissions
Configure webhooks to receive real-time notifications about thread state changes