Tasks

Audience: Developers

Tasks API Contract

Overview

The Tasks API provides endpoints for asynchronous deep research task management. All task endpoints require API key authentication.

Authentication: All endpoints require the X-API-Key header with either:

• Account API key (from account creation)

• Master API key (from GL_DEEP_RESEARCH_MASTER_API_KEY environment variable)

---

Create Task (POST /v1/tasks)

Create an asynchronous deep research task using the specified profile.

Authentication: API key required (account or master key)

Example cURL:

curl --location 'https://stag-gl-deep-research.obrol.id/v1/tasks' \
--header 'X-API-Key: your-api-key' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'query=What are the latest developments in quantum computing?' \
--data-urlencode 'profile=GPTR-QUICK' \
--data-urlencode 'webhook={"url": "https://webhook.site/your-unique-id", "secret": "your-secret"}'

Request Fields:

Field	Type	Required	Description
query	string	Yes	Query to be researched (minimum length: 1)
profile	string	Yes	Profile name (string value) to use for research configuration. The value represents the profile name, e.g., "TONGYI", "GPTR-QUICK", "GPTR-DEEP"
webhook	string	No	Optional webhook config as JSON: {"url": "...", "secret": "..."}. Both url and secret are optional. Webhook will be called when task status changes with the same payload as GET /v1/tasks/{task_id}. If secret is provided, requests include X-Webhook-Signature header for verification.

Note: The request must be sent as application/x-www-form-urlencoded form data.

Example Success Response (202 Accepted):

{
  "task_id": "your-taskgroup-id",
  "taskgroup_id": null,
  "created_at": "2024-12-02T10:00:00Z",
  "error": ""
}

Example Error Response (400 Bad Request - Empty Query):

{
  "task_id": "",
  "created_at": null,
  "error": "Query cannot be empty"
}

Example Error Response (404 Not Found - Profile Not Found):

{
  "task_id": "",
  "created_at": null,
  "error": "Profile 'INVALID_PROFILE' not found. Available profiles: ['TONGYI', 'GPTR-QUICK', 'GPTR-DEEP']"
}

Response Fields:

Field	Type	Description
task_id	string	Unique identifier for the created task
taskgroup_id	string | null	ID of the taskgroup if the task belongs to one (null for standalone tasks)
created_at	datetime (ISO 8601)	Timestamp when task was created
error	string	Error message if task creation failed (empty string if successful)

Error Handling:

• 400 Bad Request: Invalid query (empty or too short)

• 404 Not Found: Profile not found

• 500 Internal Server Error: Server error

The API uses profile-based configuration. Each profile specifies:

• The provider type (Tongyi or GPT-Researcher)

• Provider-specific parameters (model, temperature, max_tokens, etc.)

To see available profiles, use the GET /v1/profiles endpoint.

---

Get Task (GET /v1/tasks/{task_id})

Authentication: API key required (account or master key)

Authentication: API key required (account or master key)

Retrieve the full result of an asynchronous deep research task, including data and status.

Example cURL:

curl --location 'https://stag-gl-deep-research.obrol.id/v1/tasks/your-taskgroup-id'

Example Success Response (200 OK):

{
  "task_id": "your-taskgroup-id",
  "taskgroup_id": "660e8400-e29b-41d4-a716-446655440000",
  "status": "SUCCESS",
  "data": {
    "query": "What are the latest developments in quantum computing?",
    "result": "Research findings and analysis...",
    "profile": "GPTR-QUICK",
    "created_at": "2024-12-02T10:00:00Z",
    "completed_at": "2024-12-02T10:00:45Z",
    "duration": 45.23
  },
  "error": ""
}

Example Error Response (400 Bad Request - Invalid ID):

{
  "task_id": "your-taskgroup-id",
  "status": "FAILURE",
  "data": null,
  "error": "Invalid ID"
}

Example Error Response (404 Not Found - Task Not Found):

{
  "task_id": "your-taskgroup-id",
  "status": "FAILURE",
  "data": null,
  "error": "Task not found. The task may not have been executed yet or it does not exist."
}

Response Fields:

Field	Type	Description
task_id	string	Unique identifier for the task
taskgroup_id	string | null	ID of the taskgroup if the task belongs to one (null for standalone tasks)
status	string	Task status: "PENDING", "RECEIVED", "STARTED", "SUCCESS", "FAILURE", "REVOKED", "RETRY"
data	object | null	Research result data (null if status is not "SUCCESS")
data.query	string	The original research query
data.result	string	The research findings and analysis
data.profile	string | null	Profile name used for research configuration
data.duration	number | null	Duration in seconds (null if not completed)
data.created_at	datetime (ISO 8601)	Timestamp when research was initiated
data.completed_at	datetime | null	Timestamp when research was completed (null if not completed)
error	string	Error message if task failed (empty string if successful)

Status Values:

• "PENDING": Task is waiting to be processed

• "RECEIVED": Task has been received by the worker but not yet started

• "STARTED": Task execution has started

• "SUCCESS": Task completed successfully

• "FAILURE": Task failed due to an error (includes timeout scenarios)

• "REVOKED": Task was revoked/cancelled

• "RETRY": Task is being retried after a failure

Note: Status values match Celery task states. Status is retrieved directly from Celery's PostgreSQL backend, ensuring accurate real-time task state information.

Error Handling:

• 400 Bad Request: Invalid ID format

• 404 Not Found: Task not found

• 500 Internal Server Error: Server error

---

Get Task Status (GET /v1/tasks/{task_id}/status)

Authentication: API key required (account or master key)

Authentication: API key required (account or master key)

Get the lightweight status of an asynchronous deep research task without retrieving the full result data.

Example cURL:

curl --location 'https://stag-gl-deep-research.obrol.id/v1/tasks/your-taskgroup-id/status'

Example Success Response (200 OK):

{
  "task_id": "your-taskgroup-id",
  "taskgroup_id": null,
  "status": "STARTED",
  "error": ""
}

Example Error Response (400 Bad Request - Invalid ID):

{
  "task_id": "your-taskgroup-id",
  "status": "FAILURE",
  "error": "Invalid ID"
}

Example Error Response (404 Not Found - Task Not Found):

{
  "task_id": "your-taskgroup-id",
  "status": "FAILURE",
  "error": "Task not found. The task may not have been executed yet or it does not exist."
}

Response Fields:

Field	Type	Description
task_id	string	Unique identifier for the task
taskgroup_id	string | null	ID of the taskgroup if the task belongs to one (null for standalone tasks)
status	string	Task status: "PENDING", "RECEIVED", "STARTED", "SUCCESS", "FAILURE", "REVOKED", "RETRY"
error	string	Error message if task failed (empty string if successful)

Status Values:

• "PENDING": Task is waiting to be processed

• "RECEIVED": Task has been received by the worker but not yet started

• "STARTED": Task execution has started

• "SUCCESS": Task completed successfully

• "FAILURE": Task failed due to an error (includes timeout scenarios)

• "REVOKED": Task was revoked/cancelled

• "RETRY": Task is being retried after a failure

Note: Status values match Celery task states. Status is retrieved directly from Celery's PostgreSQL backend, ensuring accurate real-time task state information.

Error Handling:

• 400 Bad Request: Invalid ID format

• 404 Not Found: Task not found

• 500 Internal Server Error: Server error

Note: Task status is retrieved directly from Celery's PostgreSQL backend, providing accurate real-time task state information.

---

Get Task Stream (GET /v1/tasks/{task_id}/stream)

Retrieve streaming events for an asynchronous deep research task from Redis. This endpoint streams events stored in Redis for the given task ID as Server-Sent Events (SSE) in real-time as they become available.

Example cURL:

curl --location 'https://stag-gl-deep-research.obrol.id/v1/tasks/your-taskgroup-id/stream' \
--no-buffer

Response Format:

The endpoint returns a text/event-stream response with Server-Sent Events (SSE) format. Each event is a JSON object with the following structure:

{
  "id": "unique-event-id",
  "type": "event-type",
  "value": "event-content",
  "level": "info"
}

Event Types:

• THINKING_START: Indicates the start of thinking process

• THINKING: Contains thinking process content

• THINKING_END: Indicates the end of thinking process

• ACTIVITY: Tool execution events (tool calls and tool responses)

• RESPONSE: Final research result

Example Stream Events:

data:{"id":"uuid-1","type":"THINKING_START","value":"","level":"info"}

data:{"id":"uuid-2","type":"THINKING","value":"I need to research quantum computing developments...","level":"info"}

data:{"id":"uuid-3","type":"THINKING_END","value":"","level":"info"}

data:{"id":"uuid-4","type":"ACTIVITY","value":{"message":"Executing web_search tool with parameters: query=quantum computing"},"level":"info"}

data:{"id":"uuid-5","type":"ACTIVITY","value":{"message":"Tool web_search completed successfully. Result: Found 10 relevant articles..."},"level":"info"}

data:{"id":"uuid-6","type":"RESPONSE","value":"Based on my research, quantum computing has seen significant advances...","level":"info"}

Event Value Formats:

• THINKING events: value is a plain string containing the thinking content

• ACTIVITY events: value is an object with a message field describing the activity

• RESPONSE events: value is a plain string containing the final research result

HTTP Headers:

The response includes the following headers:

• Content-Type: text/event-stream

• Cache-Control: no-cache

• X-Accel-Buffering: no

• Connection: keep-alive

Event Retention:

Events are stored in Redis and retained for 24 hours (86400 seconds) based on DEFAULT_STREAM_REDIS_CACHE_TTL. This allows clients to fetch streaming events multiple times during the retention period even after the initial stream completes. The Redis key will expire automatically after the TTL period.

Streaming Behavior:

• The endpoint polls Redis for new events every 0.5 seconds

• Streaming continues until the task completes or a timeout is reached (5 minutes maximum wait time)

• After task completion, the stream checks for remaining events up to 10 consecutive empty reads before closing

• If the task is not found or has no streaming data, an error event is sent

Error Handling:

• 400 Bad Request: Invalid ID format

• 404 Not Found: Task not found or has no streaming data

• 500 Internal Server Error: Server error or Redis unavailable

Prerequisites:

• Redis must be configured and available

• The task must have been created and started (events are stored in Redis during task execution)

• The task must use a provider that supports streaming (Tongyi or GPT-Researcher)

Use Cases:

• Real-time monitoring of long-running research tasks

• Building user interfaces with progress indicators

• Debugging and monitoring research execution

• Retrieving task events after initial stream completion (within 24-hour retention period)