Task Management - AdCP - Ad Context Protocol

AdCP provides unified task management for tracking all async operations across media-buy and signals domains. This enables state reconciliation, progress monitoring, and webhook integration for long-running operations.

Overview

AdCP operations may complete immediately (~1 second), take processing time (~60 seconds), or require extended execution (minutes to days). Task management provides visibility and control over these async operations regardless of their domain or complexity. Core Tasks:

tasks/list - List and filter async operations for state reconciliation
tasks/get - Poll specific tasks for status, progress, and results

Key Features:

Cross-Domain Coverage: Works for both media-buy and signals operations
State Reconciliation: Prevents lost or orphaned operations
Webhook Integration: Optional push notifications for completion
Progress Tracking: Real-time status updates for active operations
Error Recovery: Detailed error information and retry guidance

Task Status Lifecycle

All AdCP operations follow a consistent status progression:

Status Definitions

Status	Description	Duration	Client Action
`submitted`	Queued for long-running execution	Hours to days	Poll periodically or wait for webhook
`working`	Actively processing	< 120 seconds	Poll frequently (5-10s intervals)
`input-required`	Paused, waiting for user input	Until input provided	Read message, provide clarification
`completed`	Successfully finished	Final	Process results, stop polling
`failed`	Failed due to error	Final	Handle error, potentially retry
`canceled`	Canceled by user	Final	Clean up, stop polling
`rejected`	Rejected before starting	Final	Review rejection reason
`auth-required`	Needs authentication	Until auth provided	Provide credentials
`unknown`	Indeterminate state	Variable	Check again or escalate

Status Transitions

Immediate Completion: Simple operations may skip to completed without intermediate states. Working vs Submitted: working indicates active processing with completion expected within 120 seconds, while submitted indicates queued execution that may take much longer.

tasks/list

List and filter async tasks across your account to enable state reconciliation and operation tracking. Response Time: ~1 second (simple database lookup) Request Schema: https://adcontextprotocol.org/schemas/v2/core/tasks-list-request.json Response Schema: https://adcontextprotocol.org/schemas/v2/core/tasks-list-response.json

Request Parameters

Parameter	Type	Required	Description
`filters`	object	No	Filter criteria for querying tasks
`sort`	object	No	Sorting parameters
`pagination`	object	No	Pagination controls
`include_history`	boolean	No	Include full conversation history for each task (default: false)

Filtering Options

Status and Type Filtering

{
  "filters": {
    "status": "submitted",
    "statuses": ["submitted", "working", "input-required"],
    "task_type": "create_media_buy",
    "task_types": ["create_media_buy", "activate_signal"]
  }
}

Domain-Specific Filtering

{
  "filters": {
    "domain": "media-buy",           // Filter by domain
    "domains": ["media-buy", "signals"],
    "task_types": [
      "create_media_buy",
      "update_media_buy", 
      "sync_creatives",
      "activate_signal",
      "get_signals"
    ]
  }
}

Date and Context Filtering

{
  "filters": {
    "created_after": "2025-01-01T00:00:00Z",
    "created_before": "2025-01-31T23:59:59Z",
    "updated_after": "2025-01-20T00:00:00Z",
    "context_contains": "nike_q1_2025",
    "task_ids": ["task_456", "task_789"],
    "has_webhook": true
  }
}

Response Structure

{
  "message": "Found 27 tasks matching your criteria. 15 are pending and may need attention.",
  "context_id": "ctx-123",
  "query_summary": {
    "total_matching": 27,
    "returned": 20,
    "domain_breakdown": {
      "media-buy": 18,
      "signals": 9
    },
    "status_breakdown": {
      "submitted": 12,
      "working": 3,
      "completed": 8,
      "failed": 4
    }
  },
  "tasks": [
    {
      "task_id": "task_456",
      "task_type": "create_media_buy",
      "domain": "media-buy",
      "status": "submitted",
      "created_at": "2025-01-22T10:00:00Z",
      "updated_at": "2025-01-22T10:00:00Z",
      "message": "Media buy requires manual approval for $150K campaign",
      "has_webhook": true
    },
    {
      "task_id": "task_789",
      "task_type": "activate_signal",
      "domain": "signals",
      "status": "completed",
      "created_at": "2025-01-22T09:45:00Z",
      "completed_at": "2025-01-22T09:46:00Z",
      "message": "Signal sent successfully to 3 endpoints",
      "has_webhook": false
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "has_more": true,
    "next_offset": 20
  }
}

Common Use Cases

State Reconciliation

Find all pending operations across domains:

{
  "filters": {
    "statuses": ["submitted", "working", "input-required"]
  },
  "sort": {
    "field": "created_at",
    "direction": "asc"
  }
}

Domain-Specific Monitoring

Track only media-buy operations:

{
  "filters": {
    "domain": "media-buy",
    "statuses": ["submitted", "working"]
  }
}

Operations Needing Attention

{
  "filters": {
    "statuses": ["input-required", "failed"],
    "updated_before": "2025-01-20T00:00:00Z"  // Old stuck tasks
  }
}

Lost Connection Recovery

Recover from lost task submissions by examining conversation history:

{
  "filters": {
    "created_after": "2025-01-22T10:00:00Z"
  },
  "include_history": true
}

Then check history[0].data to see original requests and identify your lost task:

tasks.tasks.forEach(task => {
  const originalRequest = task.history?.[0]?.data;
  if (originalRequest?.buyer_ref === "nike_q1_2025") {
    console.log(`Found my lost task: ${task.task_id}`);
  }
});

tasks/get

Poll a specific task by ID to check status, progress, and retrieve results when complete. Response Time: ~1 second (simple database lookup) Request Schema: https://adcontextprotocol.org/schemas/v2/core/tasks-get-request.json Response Schema: https://adcontextprotocol.org/schemas/v2/core/tasks-get-response.json

Request Parameters

Parameter	Type	Required	Description
`task_id`	string	Yes	Unique identifier of the task to retrieve
`include_history`	boolean	No	Include full conversation history for this task (default: false)

Response Structure

Basic Task Information

{
  "message": "Media buy creation is 75% complete. Currently validating inventory availability.",
  "context_id": "ctx-123",
  "task_id": "task_456",
  "task_type": "create_media_buy",
  "domain": "media-buy",
  "status": "working",
  "created_at": "2025-01-22T10:00:00Z",
  "updated_at": "2025-01-22T10:15:00Z",
}

Progress Information

{
  "progress": {
    "percentage": 75,
    "current_step": "validating_inventory_availability",
    "total_steps": 4,
    "step_number": 3
  }
}

Task with Conversation History

{
  "status": "completed",
  "completed_at": "2025-01-22T10:25:00Z",
  "history": [
    {
      "timestamp": "2025-01-22T10:00:00Z",
      "type": "request",
      "data": {
        "buyer_ref": "nike_q1_2025",
        "brief": "Premium CTV inventory for Nike campaign"
      }
    },
    {
      "timestamp": "2025-01-22T10:25:00Z",
      "type": "response",
      "data": {
        "media_buy_id": "mb_987654321",
        "packages": [{ "package_id": "pkg_abc123" }]
      }
    }
  ]
}

Failed Task Errors

{
  "status": "failed",
  "completed_at": "2025-01-22T10:20:00Z",
  "error": {
    "code": "insufficient_inventory",
    "message": "Requested targeting yielded 0 available impressions",
    "details": {
      "domain": "media-buy",
      "operation": "create_media_buy",
      "specific_context": {}
    }
  }
}

Polling Patterns

Basic Polling Loop

async function pollTask(taskId) {
  while (true) {
    const response = await session.call('tasks/get', { 
      task_id: taskId
    });
    
    switch (response.status) {
      case 'completed':
        return response; // Get full result from history if needed
        
      case 'failed':
        throw new Error(`Task failed: ${response.error.message}`);
        
      case 'input-required':
        const input = await promptUser(response.message);
        // Continue conversation with same context_id
        return await handleUserInput(response.context_id, input);
        
      case 'working':
        console.log(`Progress: ${response.progress?.percentage || 0}%`);
        await sleep(5000); // Poll working tasks frequently
        break;
        
      case 'submitted':
        console.log(`Task queued for long-running execution`);
        await sleep(60000); // Poll submitted tasks less frequently
        break;
    }
  }
}

Smart Polling with Domain Awareness

async function smartPollTask(taskId) {
  let pollInterval = 2000;
  const maxInterval = 60000;
  
  while (true) {
    const response = await session.call('tasks/get', { task_id: taskId });
    
    if (['completed', 'failed', 'canceled'].includes(response.status)) {
      return response;
    }
    
    // Adjust polling based on domain and status
    if (response.status === 'working') {
      pollInterval = response.domain === 'signals' ? 2000 : 5000;
    } else if (response.status === 'submitted') {
      pollInterval = response.domain === 'media-buy' ? 60000 : 30000;
    }
    
    await sleep(Math.min(pollInterval, maxInterval));
  }
}

Protocol Integration

Task management works consistently across all AdCP protocols.

MCP Integration

// List tasks
const taskList = await session.call('tasks/list', {
  filters: { statuses: ['submitted', 'working'] }
});

// Poll specific task
const taskStatus = await session.call('tasks/get', {
  task_id: 'task_456'
});

A2A Integration

Natural Language

await a2a.send({
  message: {
    parts: [{
      kind: "text",
      text: "Show me all pending media buy tasks from the last week"
    }]
  }
});

Explicit Skill Invocation

await a2a.send({
  message: {
    parts: [{
      kind: "data",
      data: {
        skill: "tasks/list",
        parameters: {
          filters: {
            domain: "media-buy",
            statuses: ["submitted", "working"],
            created_after: "2025-01-15T00:00:00Z"
          }
        }
      }
    }]
  }
});

Webhook Integration

For async operations, you can configure webhooks instead of polling. See Protocol Comparison - Push Notifications for protocol differences and Core Concepts - Webhook Reliability for implementation patterns. Webhook trigger conditions: Webhooks fire when the task type supports async, pushNotificationConfig is provided, and the task actually runs asynchronously (initial response is working or submitted).

Error Handling

Common Error Scenarios

Task Not Found: Invalid task ID or access permissions
Invalid Filters: Malformed filter criteria in tasks/list
Pagination Errors: Invalid offset or limit values
Permission Denied: Task exists but user lacks access

Error Response Format

{
  "status": "failed",
  "message": "Task not found or access denied",
  "context_id": "ctx-123",
  "errors": [{
    "code": "task_not_found", 
    "message": "No task found with ID 'task_456' for this account",
    "field": "task_id"
  }]
}

Best Practices

State Reconciliation

Run tasks/list with pending filters during application startup
Check for old tasks that may be stuck in submitted status
Use domain filtering to focus on relevant operation types
Include webhook status to understand notification expectations

Performance Optimization

Use pagination for accounts with many operations
Filter by date ranges to limit results to relevant periods
Use include_history: false by default to keep responses lightweight
Implement exponential backoff for polling loops

Monitoring and Alerting

Monitor input-required tasks for user attention needs
Alert on tasks stuck in submitted status beyond expected duration
Track failed tasks for error reporting and system health
Use domain breakdown to understand operation distribution

Integration Patterns

Store task IDs with your application entities for later reference
Use webhooks as primary notification mechanism, polling as backup
Implement proper error handling for both webhook and polling failures
Consider domain-specific polling intervals and timeout values

Core Concepts - Protocol fundamentals and design principles
MCP Guide - MCP-specific implementation patterns
A2A Guide - A2A-specific integration examples
Media Buy Reference - Domain-specific task documentation
Signals Reference - Signal-specific task documentation

Getting Started

Protocols

Signals

Curation Protocol

Media Buy

Creative

Reference

Community

Documentation Index

​Overview

​Task Status Lifecycle

​Status Definitions

​Status Transitions

​tasks/list

​Request Parameters

​Filtering Options

​Status and Type Filtering

​Domain-Specific Filtering

​Date and Context Filtering

​Response Structure

​Common Use Cases

​State Reconciliation

​Domain-Specific Monitoring

​Operations Needing Attention

​Lost Connection Recovery

​tasks/get

​Request Parameters

​Response Structure

​Basic Task Information

​Progress Information

​Task with Conversation History

​Failed Task Errors

​Polling Patterns

​Basic Polling Loop

​Smart Polling with Domain Awareness

​Protocol Integration

​MCP Integration

​A2A Integration

​Natural Language

​Explicit Skill Invocation

​Webhook Integration

​Error Handling

​Common Error Scenarios

​Error Response Format

​Best Practices

​State Reconciliation

​Performance Optimization

​Monitoring and Alerting

​Integration Patterns

​Related Documentation

Overview

Task Status Lifecycle

Status Definitions

Status Transitions

tasks/list

Request Parameters

Filtering Options

Status and Type Filtering

Domain-Specific Filtering

Date and Context Filtering

Response Structure

Common Use Cases

State Reconciliation

Domain-Specific Monitoring

Operations Needing Attention

Lost Connection Recovery

tasks/get

Request Parameters

Response Structure

Basic Task Information

Progress Information

Task with Conversation History

Failed Task Errors

Polling Patterns

Basic Polling Loop

Smart Polling with Domain Awareness

Protocol Integration

MCP Integration

A2A Integration

Natural Language

Explicit Skill Invocation

Webhook Integration

Error Handling

Common Error Scenarios

Error Response Format

Best Practices

State Reconciliation

Performance Optimization

Monitoring and Alerting

Integration Patterns

Related Documentation