---
title: "Retrieve all executions with admin filtering and cross-user visibility."
method: GET
path: "/api/v1/execution"
---

# Retrieve all executions with admin filtering and cross-user visibility.

`GET /api/v1/execution`

**Authentication**: JWT token required
**Access**: Admin users can see all executions, regular users see only their own
**Admin Features**: ADMIN+ users can filter by user_id to view other users'
  executions

**Query Parameters**:
- `user_id`: Filter executions by specific user ID (admin-only feature)
- `updated_at`: Filter executions started after specific timestamp (ISO 8601)
- `status`: Filter by execution status (PENDING, RUNNING, SUCCESS, FAILED,
  CANCELLED)
- `include`: Comma-separated list of additional fields to include
- `exclude`: Comma-separated list of fields to exclude
- `filter`: General search/filter across execution attributes
- `sort`: Sort field (prefix with '-' for descending, e.g., '-updated_at')
- `page`: Page number for pagination (triggers pagination when provided)
- `per_page`: Items per page (1-100, default: 20, max without pagination:
  varies by permission)

**Response Schema (without pagination)**:
```json
{
  "data": [
    {
      "id": "exec-123",
      "script_id": "script-456",
      "status": "SUCCESS",
      "params": {
        "region": "africa",
        "analysis_type": "vegetation_change"
      },
      "user_id": "user-789",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T11:45:00Z",
      "start_time": "2025-01-15T10:31:00Z",
      "end_time": "2025-01-15T11:45:00Z",
      "results": {
        "analysis_complete": true,
        "output_files": ["vegetation_2023.tif", "change_summary.json"]
      }
    }
  ]
}
```

**Response Schema (with pagination)**:
```json
{
  "data": [...],
  "page": 1,
  "per_page": 20,
  "total": 1250
}
```

**Admin Query Examples**:
- `?user_id=123` - View executions for specific user (admin only)
- `?status=FAILED` - Find all failed executions across system
- `?updated_at=2025-01-15T00:00:00Z` - Find executions updated since date

**Regular User Behavior**:
- Non-admin users: Only see their own executions regardless of user_id parameter
- Admin users: Can see all executions, can filter by user_id

**Filtering Examples**:
- `?filter=vegetation` - Find executions with "vegetation" in script or params
- `?filter=2024-12` - Find executions from December 2024
- `?status=RUNNING&sort=-created_at` - Find currently running executions,
  newest first

**Sorting Examples**:
- `?sort=updated_at` - Sort by last update ascending
- `?sort=-created_at` - Sort by creation time descending (newest first)
- `?sort=status` - Sort by execution status alphabetically

**Timestamp Filtering**:
- `updated_at` parameter accepts ISO 8601 format: `2025-01-15T10:30:00Z`
- Returns executions that started after the specified timestamp
- Useful for incremental synchronization and monitoring

**Error Responses**:
- `401 Unauthorized`: JWT token required
- `500 Internal Server Error`: Failed to retrieve executions

## Response `200`

Success

- object

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error

---

[API](https://skmtc.dev/trends/apis/trends-earth-api.md) · [All operations](https://skmtc.dev/trends/apis/trends-earth-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/trends/trends-earth-api/revisions/6bdbc0b84666/schema)