Kirha Docs - Tasks

What is a task

A task is an asynchronous, deep research job. Unlike kirha.search() which returns results synchronously from a single vertical, a task searches across multiple verticals, validates findings with multiple agents, and can retry failed steps automatically. This produces more thorough, more accurate answers at the cost of more time and credits.

search gives you a fast answer from a single vertical. task is a full research pipeline that gathers data, cross-checks it, and reports back.

Task vs Search

	Search	Task
Response	Synchronous	Asynchronous (polling)
Vertical scope	Single vertical	Multi-vertical
Depth of answer	Quick, surface-level	Deep, comprehensive
Validation	None	Multi-agent validation
Retries on failure	No	Automatic retries
Credit usage	Lower	Higher
Best for	Simple lookups, real-time data	Complex research, cross-domain analysis

Task lifecycle

Status	Description
`Queued`	Task is waiting to be processed
`Researching`	Gathering data across multiple verticals and providers
`Validating`	Multiple agents cross-check and validate the results. May retry the research step if needed
`Summarizing`	Final result is being generated from validated data
`Completed`	Task finished successfully, result is available
`Failed`	Task failed, error is available

Create a task

Use kirha.task(query, options?) to create a task.

import { Kirha } from "kirha";

const kirha = new Kirha({
  apiKey: process.env.KIRHA_API_KEY,
});

const task = await kirha.task( 
  "Compare the AI strategies of Google, Microsoft, and Meta: key acquisitions, patent filings, and recent product launches", 
  { instruction: "Focus on 2024-2025 developments" } 
); 
console.log("Task created:", task.id);

Credit usage

Tasks consume more credits than regular searches because they query multiple verticals and run multi-agent validation. You can track usage on the Dashboard.

Wait for completion

Call task.wait() to poll the task until it completes, fails, or times out.

import { Kirha, TaskStatus } from "kirha";

const kirha = new Kirha({
  apiKey: process.env.KIRHA_API_KEY,
});

const task = await kirha.task(
  "Compare the AI strategies of Google, Microsoft, and Meta",
  { instruction: "Focus on 2024-2025 developments" }
);

const result = await task.wait(); 
if (result.status === TaskStatus.Completed) { 
  console.log("Result:", result.result); 
} else { 
  console.log("Error:", result.error); 
}

Check status manually

You can check the task status or fetch the result without waiting:

const status = await task.status(); 
console.log(status.status); // "Queued" | "Researching" | ...

const result = await task.result(); 
console.log(result.result);

Status getters

The Task instance exposes getters to check the current cached status without making an API call:

task.isCompleted  // true if status is "Completed"
task.isFailed     // true if status is "Failed"
task.isPending    // true if status is "Queued", "Researching", "Validating", or "Summarizing"
task.isQueued     // true if status is "Queued"
task.isResearching // true if status is "Researching"
task.isValidating  // true if status is "Validating"
task.isSummarizing // true if status is "Summarizing"

Task options

Prop

Type

Wait options

Prop

Type

Tasks

On this page