---
title: Tasks | 0ct
description: Create and manage scheduled AI tasks
---

# Tasks

Tasks are the core building block of 0ct. A task defines what you want AI to do, when to do it, where to get data from, and where to deliver results.

## Task Components

Every task consists of:

| Component    | Description               | Required |
| ------------ | ------------------------- | -------- |
| Name         | Human-readable identifier | Yes      |
| Prompt       | Instructions for the AI   | Yes      |
| Model        | Which AI model to use     | Yes      |
| Schedule     | When to run               | Yes      |
| Sources      | Data connections          | No       |
| Skills       | Reusable instructions     | No       |
| Destinations | Where to deliver results  | No       |

## Creating a Task

### Via Dashboard

1. Navigate to **Tasks** in the sidebar
2. Click **New Task**
3. Fill in the task details
4. Click **Create Task**

### Via SDK

```
import Oct from '0ct';


const client = new Oct({
  apiKey: process.env.OCT_API_KEY
});


const task = await client.promptly.tasks.create({
  name: 'Weekly Report',
  prompt: 'Generate a summary of this week\'s key metrics...',
  modelId: 'anthropic/claude-3-5-sonnet',
  frequency: 'weekly',
  scheduledDay: 'monday',
  scheduledTime: '09:00',
  isActive: true
});
```

## Scheduling Options

### Frequency Types

**Hourly**: Run every N hours

```
{
  frequency: 'hourly',
  hourlyInterval: 2  // Every 2 hours
}
```

**Daily**: Run once per day at a specific time

```
{
  frequency: 'daily',
  scheduledTime: '09:00'  // 9 AM
}
```

**Weekly**: Run on specific days

```
{
  frequency: 'weekly',
  scheduledDay: 'monday',
  scheduledTime: '08:00'
}
```

**One-time**: Run once at a specific date/time

```
{
  frequency: 'once',
  scheduledDate: '2026-02-15',
  scheduledTime: '15:00'
}
```

### Timezone Handling

All times are in your organization’s configured timezone. Set your timezone in **Settings** → **Organization**.

## Prompt Engineering

### Best Practices

1. **Be Specific**: Clearly describe what you want
2. **Provide Context**: Explain why the task matters
3. **Define Output Format**: Specify how results should be structured
4. **Set Boundaries**: Clarify what to include/exclude

### Example Prompts

**Good Prompt**:

```
Analyze our GitHub repository activity from the past week.


For each contributor, report:
- Number of commits
- Lines added/removed
- Key changes made


Summarize overall team velocity and highlight any concerning trends.
Format as a markdown report suitable for our weekly standup.
```

**Weak Prompt**:

```
Tell me about our GitHub.
```

### Using Variables

Prompts can include dynamic variables:

```
Generate a {{frequency}} report for {{organization_name}}.
Today's date is {{current_date}}.
```

## Attaching Sources

Sources give your task access to real-time data. When sources are attached, the AI can query them during execution.

```
// Attach sources when creating
const task = await client.promptly.tasks.create({
  name: 'Project Status',
  prompt: 'Summarize open issues and recent activity...',
  modelId: 'openai/gpt-4o',
  frequency: 'daily',
  scheduledTime: '09:00',
  sources: ['source_linear_abc123', 'source_github_def456']
});


// Or update existing task
await client.promptly.tasks.update(task.id, {
  sources: ['source_slack_ghi789']
});
```

## Attaching Skills

Skills provide reusable instructions that enhance your prompts:

```
const task = await client.promptly.tasks.create({
  name: 'Customer Email',
  prompt: 'Draft a response to this customer inquiry...',
  modelId: 'anthropic/claude-3-5-sonnet',
  frequency: 'hourly',
  hourlyInterval: 1,
  skills: ['skill_writing_style', 'skill_product_knowledge']
});
```

Skills are prepended to your prompt, giving the AI consistent context.

## Configuring Destinations

Destinations define where results are delivered:

```
const task = await client.promptly.tasks.create({
  name: 'Daily Digest',
  prompt: 'Compile today\'s key updates...',
  modelId: 'openai/gpt-4o',
  frequency: 'daily',
  scheduledTime: '18:00',
  destinations: ['dest_email_team', 'dest_slack_channel']
});
```

## Managing Tasks

### List All Tasks

```
const tasks = await client.promptly.tasks.list();


for (const task of tasks.data) {
  console.log(`${task.name}: ${task.isActive ? 'Active' : 'Paused'}`);
}
```

### Update a Task

```
await client.promptly.tasks.update('task_abc123', {
  prompt: 'Updated instructions...',
  isActive: false  // Pause the task
});
```

### Delete a Task

```
await client.promptly.tasks.delete('task_abc123');
```

### Trigger Manual Run

Don’t wait for the schedule—run immediately:

```
const run = await client.promptly.tasks.run('task_abc123');
console.log('Run ID:', run.id);
```

## Monitoring Runs

### View Run History for a Task

```
const runs = await client.promptly.tasks.listRuns('task_abc123', {
  limit: 10
});


for (const run of runs) {
  console.log(`${run.id}: ${run.status}`);
  console.log(`Tokens: ${run.tokensUsed}`);
}
```

### View All Runs

```
const allRuns = await client.promptly.runs.list({
  organizationId: 'org_abc123',
  limit: 50
});
```

### Run Statuses

| Status      | Description                   |
| ----------- | ----------------------------- |
| `pending`   | Scheduled, waiting to execute |
| `running`   | Currently executing           |
| `completed` | Finished successfully         |
| `failed`    | Encountered an error          |

## Error Handling

Tasks can fail for various reasons:

- Model API errors
- Source connection failures
- Destination delivery issues
- Prompt/response validation errors

Failed runs include error details:

```
const run = await client.promptly.runs.get('run_failed');


if (run.status === 'failed') {
  console.log('Error:', run.error);
}
```

## Next Steps

- [Connect Sources](/guides/sources/index.md) - Give tasks access to your data
- [Create Skills](/guides/skills/index.md) - Build reusable instructions
- [Configure Destinations](/guides/destinations/index.md) - Set up delivery channels