BlocktionBlocktion Docs
Platform•GitHub

Documentation

Getting Started
Parameters & Configuration
Authentication
Workflows
Blocks
Handlers
Sessions
Providers
DataStores
Triggers
Marketplace

Sessions

Track and manage workflow execution sessions with real-time monitoring

What is a Session?

A session represents a single execution of a workflow. It tracks status transitions, logs, outputs, and supports control commands like start, pause, resume, cancel. Sessions are queryable and auditable via the API.

Session Statuses

pending

Session is waiting to be executed

running

Session is currently executing

completed

Session finished successfully

failed

Session encountered an error

cancelled

Session was cancelled by user

Session Lifecycle

Understanding how sessions progress through different states

Pending
Running
Completed
Sessions can also transition to Failed or Cancelled states at any point during execution.

Overview

Sessions track the execution of workflows and provide real-time monitoring capabilities.

Session States

  • • Pending - Waiting to start
  • • Running - Currently executing
  • • Completed - Successfully finished
  • • Failed - Execution failed
  • • Cancelled - Manually cancelled

Key Features

  • • Real-time execution monitoring
  • • Command execution (start, pause, resume, stop)
  • • Log retrieval and output tracking
  • • Session management and cleanup

Endpoints

GET/api/sessions

List Sessions

List execution sessions with pagination and filters

Query Parameters

workflow_id(string)Filter by workflow ID
status(string)Filter by session status
search(string)Search by name or description
page(number)Page number (starts at 1)
limit(number)Items per page (default 10)

Response

{
  "data": [
    {
      "id": "session_123456",
      "workflow_id": "workflow_789012",
      "name": "Email Marketing Campaign",
      "description": "Send promotional emails to subscribers",
      "status": "running",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:31:00Z",
      "started_at": "2024-01-15T10:31:00Z",
      "completed_at": null,
      "user_id": "user_456789"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10
}

cURL Example

curl -X GET "https://api.blocktion.io/api/sessions" \
  -H "Authorization: Bearer <your_access_token>"
GET/api/sessions/{session_id}

Get Session

Get session by ID

Response

{
  "data": {
    "id": "session_123456",
    "workflow_id": "workflow_789012",
    "name": "Email Marketing Campaign",
    "description": "Send promotional emails to subscribers",
    "status": "pending",
    "created_at": "2024-01-15T10:30:00Z",
    "user_id": "user_456789"
  }
}

cURL Example

curl -X GET "https://api.blocktion.io/api/sessions/{session_id}" \
  -H "Authorization: Bearer <your_access_token>"
POST/api/sessions

Create Session

Create a new workflow execution session

Request Body

{
  "workflow_id": "string (required)",
  "node_id": "string (required, trigger node id)",
  "inputs": "object (optional)"
}

Response

{
  "data": {
    "id": "session_123456",
    "workflow_id": "workflow_789012",
    "name": "Email Marketing Campaign",
    "status": "pending",
    "created_at": "2024-01-15T10:30:00Z",
    "user_id": "user_456789"
  }
}

cURL Example

curl -X POST "https://api.blocktion.io/api/sessions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
  "workflow_id": "string (required)",
  "node_id": "string (required, trigger node id)",
  "inputs": "object (optional)"
}'
PUT/api/sessions/{session_id}

Update Session

Update session metadata (name/description)

Request Body

{
  "name": "string (optional)",
  "description": "string (optional)"
}

Response

{
  "data": {
    "id": "session_123456",
    "name": "Updated Name",
    "description": "Updated Description"
  }
}

cURL Example

curl -X PUT "https://api.blocktion.io/api/sessions/{session_id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
  "name": "string (optional)",
  "description": "string (optional)"
}'
DELETE/api/sessions/{session_id}

Delete Session

Delete a session

Response

{
  "data": {
    "success": true,
    "id": "session_123456"
  }
}

cURL Example

curl -X DELETE "https://api.blocktion.io/api/sessions/{session_id}" \
  -H "Authorization: Bearer <your_access_token>"
POST/api/sessions/{session_id}/command

Execute Command

Execute a command on a session (start, pause, resume, stop)

Request Body

{
  "command": "string (required)"
}

Response

{
  "data": {
    "id": "session_123456",
    "status": "running"
  }
}

cURL Example

curl -X POST "https://api.blocktion.io/api/sessions/{session_id}/command" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
  "command": "string (required)"
}'
GET/api/sessions/{session_id}/logs

Get Session Logs

Retrieve execution logs for a session

Query Parameters

from_timestamp(string)Return logs from this timestamp
limit(number)Maximum number of log entries (1-1000)

Response

{
  "data": [
    {
      "id": "log_123456",
      "level": "info",
      "message": "Session started",
      "timestamp": "2024-01-15T10:31:00Z"
    }
  ]
}

cURL Example

curl -X GET "https://api.blocktion.io/api/sessions/{session_id}/logs" \
  -H "Authorization: Bearer <your_access_token>"
GET/api/sessions/{session_id}/outputs

Get Session Outputs

Get session execution outputs

Response

{
  "data": {
    "result": {}
  }
}

cURL Example

curl -X GET "https://api.blocktion.io/api/sessions/{session_id}/outputs" \
  -H "Authorization: Bearer <your_access_token>"
POST/api/sessions/{session_id}/cancel

Cancel Session

Cancel a running session

Response

{
  "data": {
    "success": true,
    "id": "session_123456"
  }
}

cURL Example

curl -X POST "https://api.blocktion.io/api/sessions/{session_id}/cancel" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>"

Best Practices

Guidelines for managing sessions effectively

Session Management

  • • Monitor session status regularly
  • • Implement proper error handling
  • • Use meaningful session names and descriptions
  • • Clean up completed sessions periodically

Performance

  • • Set appropriate timeouts for long-running sessions
  • • Use pagination for large log collections
  • • Implement retry logic for failed sessions
  • • Monitor resource usage and execution time