Running Tasks

With your task defined and a worker running, you can import the task wherever you need it and invoke it.

Run and wait

Call a task and block until you get the result back. Use this for synchronous workflows like fan-out, LLM calls, or any time you need the output before continuing.

from examples.child.worker import SimpleInput, child_task

child_task.run(SimpleInput(message="Hello, World!"))

result = await child_task.aio_run(SimpleInput(message="Hello, World!"))

const res = await parent.run(
  {
    Message: 'HeLlO WoRlD',
  },
  {
    additionalMetadata: {
      test: 'test',
    },
  }
);

// 👀 Access the results of the Task
console.log(res.TransformedMessage);

result, err := task.Run(context.Background(), SimpleInput{Message: "Hello, World!"})
if err != nil {
	return err
}

result = CHILD_TASK_WF.run({ "message" => "Hello, World!" })

# In Ruby, run is synchronous
result = CHILD_TASK_WF.run({ "message" => "Hello, World!" })

Spawning tasks from within a task

You can spawn tasks from within a task. This is useful for composing tasks together, fanning out batched tasks, or creating conditional workflows.

@hatchet.task(name="SpawnTask")
async def spawn(input: EmptyModel, ctx: Context) -> dict[str, Any]:
    # Simply run the task with the input we received
    result = await child_task.aio_run(
        input=SimpleInput(message="Hello, World!"),
    )

    return {"results": result}

Running tasks in parallel

result1 = child_task.aio_run(SimpleInput(message="Hello, World!"))
result2 = child_task.aio_run(SimpleInput(message="Hello, Moon!"))

#  gather the results of the two tasks
results = await asyncio.gather(result1, result2)

#  print the results of the two tasks
print(results[0]["transformed_message"])
print(results[1]["transformed_message"])

Fire and forget

Enqueue a task without waiting for the result. Use this for background jobs like sending emails, processing uploads, or kicking off long-running pipelines.

class HelloInput(BaseModel):
    name: str


class HelloOutput(BaseModel):
    greeting: str


@hatchet.task(input_validator=HelloInput)
async def say_hello(input: HelloInput, ctx: Context) -> HelloOutput:
    return HelloOutput(greeting=f"Hello, {input.name}!")

ref = say_hello.run_no_wait(input=HelloInput(name="World"))

ref = await say_hello.aio_run_no_wait(input=HelloInput(name="Async World"))

import { simple } from './workflow';
// ...

async function main() {
  // 👀 Enqueue the workflow
  const run = await simple.runNoWait({
    Message: 'hello',
  });

  // 👀 Get the run ID of the workflow
  const runId = await run.getWorkflowRunId();
  // It may be helpful to store the run ID of the workflow
  // in a database or other persistent storage for later use
  console.log(runId);

runRef, err := task.RunNoWait(context.Background(), SimpleInput{Message: "Hello, World!"})
if err != nil {
	return err
}

fmt.Println(runRef.RunId)

SAY_HELLO = hatchet.task(name: "say_hello") do |input, ctx|
  { "greeting" => "Hello, #{input['name']}!" }
end

ref = SAY_HELLO.run_no_wait({ "name" => "World" })

# In Ruby, run_no_wait is the equivalent of async enqueuing
ref = SAY_HELLO.run_no_wait({ "name" => "World" })

Subscribing to results later

The run_no_wait method returns a WorkflowRunRef which includes a listener for the result of the task, so you can subscribe at a later time.

result = ref.result()

result = await ref.aio_result()

Triggering from the dashboard

In the Hatchet Dashboard, navigate to “Task Runs” in the left sidebar and click “Trigger Run” at the top right. You can specify run parameters such as Input, Additional Metadata, and the Scheduled Time.

Where you can trigger from

• Same codebase or monorepo - import your task and call run, run_no_wait, or other trigger methods directly. Your API server, CLI, or another service in the same repo can use the same task definition.
• External API or separate service (polyrepo) - when the triggering code can’t import the task definition (different repo, language, or microservice), use a stub: a Hatchet task with the same name and input/output types but no implementation. See Inter-Service Triggering for details.
• From the CLI - use the hatchet run command to trigger tasks from the command line.
• From the Dashboard - use the Hatchet dashboard to trigger tasks from the web interface.

Other trigger styles

Hatchet supports additional trigger patterns for more advanced use cases:

Next steps

Now that you can run tasks, explore Durable Workflows to compose multiple tasks into pipelines with dependencies and checkpointing.