Examples

Audience: End users

Quick Start Guide

This guide gets you started with the GL Open DeepResearch service using the async task (and taskgroup) API. Create a task or task group, then stream events or poll for status and the final result.

Prerequisites

• API Key from GL Open DeepResearch Team

• Base URL: https://stag-gl-deep-research.obrol.id

Profile-based usage

GL Open DeepResearch is profile-based: every research request (task or taskgroup) must include a profile name. The profile defines which provider runs (e.g. Tongyi or GPT-Researcher) and with which settings (model, depth, timeouts). You only send the profile name and your query—no provider or model config in the request body.

In the steps below we use the GPTR-QUICK profile. You can list available profiles with GET /v1/profiles. To use a different model (e.g. Claude) or create your own configuration, create a new profile and then use its name in your requests. For details and an example (create a new profile and use it with Claude), see Research Profiles — Examples.

Step 1: Get Your API Key

Contact the GL Open DeepResearch Team to obtain your API key. This key is required for all API requests.

Step 2: Create a Task Group

The Task Groups API allows you to create and manage multiple research tasks with shared configuration. Start by creating a task group:

curl -X POST 'https://stag-gl-deep-research.obrol.id/v1/taskgroup' \
  -H 'X-API-Key: your-api-key' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'query=What are the latest developments in quantum computing?' \
  --data-urlencode 'profile=GPTR-QUICK'

Response:

{
  "taskgroup_id": "your-taskgroup-id",
  "created_at": "2024-12-15T10:00:00Z",
  "tasks": [
    "your-task-id"
  ],
  "errors": null
}

Note: Save the taskgroup_id and tasks array - you'll need these to track your research tasks.

Creating Multiple Tasks

You can also create multiple tasks at once by passing an array of queries:

curl -X POST 'https://stag-gl-deep-research.obrol.id/v1/taskgroup' \
  -H 'X-API-Key: your-api-key' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'query=["What is AI?", "What is machine learning?", "What is deep learning?"]' \
  --data-urlencode 'profile=GPTR-QUICK'

Step 3: Get Streaming Response for Each Task

To monitor the progress of your research tasks in real-time, you can stream events from each task. There are two ways to stream:

Stream from a Specific Task

Get streaming events for a specific task within a task group:

curl -N 'https://stag-gl-deep-research.obrol.id/v1/taskgroup/your-taskgroup-id/tasks/your-task-id/stream' \
  -H 'X-API-Key: your-api-key'

Or stream directly from the task (if you have the task ID):

curl -N 'https://stag-gl-deep-research.obrol.id/v1/tasks/your-task-id/stream' \
  -H 'X-API-Key: your-api-key'

Stream from All Tasks in a Group

Get compiled streaming events from all tasks in a task group:

curl -N 'https://stag-gl-deep-research.obrol.id/v1/taskgroup/your-taskgroup-id/stream' \
  -H 'X-API-Key: your-api-key'

Streaming Response Format:

The endpoint returns Server-Sent Events (SSE) with the following 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 Output:

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":"RESPONSE","value":"Based on my research, quantum computing has seen significant advances...","level":"info"}

Note: Events are retained in Redis for 24 hours, allowing you to fetch streaming events multiple times during the retention period.

Step 4: Get Task Status

Check the status of a specific task without retrieving the full result:

curl 'https://stag-gl-deep-research.obrol.id/v1/tasks/your-task-id/status' \
  -H 'X-API-Key: your-api-key'

Response:

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

Task 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

• REVOKED: Task was revoked/cancelled

• RETRY: Task is being retried after a failure

Get Task Group Status

You can also check the overall status of a task group:

curl 'https://stag-gl-deep-research.obrol.id/v1/taskgroup/your-taskgroup-id' \
  -H 'X-API-Key: your-api-key'

Response:

{
  "taskgroup_id": "your-taskgroup-id",
  "status": "SUCCESS",
  "profile": "GPTR-QUICK",
  "created_at": "2024-12-15T10:00:00Z",
  "updated_at": "2024-12-15T10:05:00Z",
  "webhook": null,
  "tasks": [
    "your-task-id"
  ]
}

Task Group Status Values:

• EMPTY: Task group has no tasks

• PENDING: At least one task is pending, but no tasks have started yet

• STARTED: At least one task has started

• SUCCESS: All tasks completed successfully

• FAILURE: All tasks failed

• PARTIAL_FAILURE: Some tasks succeeded, some failed

Step 5: Retrieve Final Result

Once a task has completed (status is SUCCESS), retrieve the final research result:

curl 'https://stag-gl-deep-research.obrol.id/v1/tasks/your-task-id' \
  -H 'X-API-Key: your-api-key'

Response:

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

Get Task Result from Task Group

You can also retrieve a task result through the task group endpoint:

curl 'https://stag-gl-deep-research.obrol.id/v1/taskgroup/your-taskgroup-id/tasks/your-task-id' \
  -H 'X-API-Key: your-api-key'

This returns the same response format as the direct task endpoint.

Available Profiles

To see all available research profiles:

curl 'https://stag-gl-deep-research.obrol.id/v1/profiles' \
  -H 'X-API-Key: your-api-key'

Response:

{
  "profiles": [
    {
      "name": "TONGYI",
      "provider": "tongyi",
      "params": {
        "model": "Alibaba-NLP/Tongyi-DeepResearch-30B-A3B",
        "max_tokens": 10000,
        "temperature": 0.6,
        "max_depth": 7,
        "timeout_seconds": 900
      },
      "description": "Tongyi Deep Research Agent..."
    },
    {
      "name": "GPTR-QUICK",
      "provider": "gptr",
      "params": {
        "config_data": {...},
        "report_type": "research_report"
      },
      "description": "GPT-Researcher profile with SmartSearch..."
    }
  ],
  "default_profile": "GPTR-QUICK"
}

Next Steps

• Review the API Documentation for detailed endpoint information

• Learn about Research Profiles for understanding profile configuration

• Check Available Open Source Deep Research for open source details