> ## Documentation Index
> Fetch the complete documentation index at: https://api-tools.memories.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Task Status
> Query the current status and progress of a screenplay extraction task
**Product**: Visual Agents
**Use case**: Managed endpoints powering Memories.ai's open-source video search and editing agents (queries, video clipping/editing, screenplay extraction)
**Host**: `https://mavi-backend.memories.ai/serve/api/v2`
**Auth**: `Authorization: sk-mavi-...` (no `Bearer` prefix)
This endpoint returns the current status of a screenplay extraction task, including progress information for running tasks and error details for failed tasks.
### Code Examples
```javascript fetch theme={null}
const BASE_URL = "https://mavi-backend.memories.ai/serve/api/v2";
const API_KEY = "sk-mavi-...";
const taskId = "ros-sd-20260313-a3f8c2b1";
const response = await fetch(`${BASE_URL}/screenplay/tasks/${taskId}`, {
method: 'GET',
headers: {
'Authorization': API_KEY
}
});
const data = await response.json();
console.log(data);
```
```javascript axios theme={null}
import axios from 'axios';
const BASE_URL = "https://mavi-backend.memories.ai/serve/api/v2";
const API_KEY = "sk-mavi-...";
const taskId = "ros-sd-20260313-a3f8c2b1";
const response = await axios.get(`${BASE_URL}/screenplay/tasks/${taskId}`, {
headers: {
'Authorization': API_KEY
}
});
console.log(response.data);
```
```python Python theme={null}
import requests
BASE_URL = "https://mavi-backend.memories.ai/serve/api/v2"
API_KEY = "sk-mavi-..."
HEADERS = {
"Authorization": f"{API_KEY}"
}
def get_screenplay_task_status(task_id):
url = f"{BASE_URL}/screenplay/tasks/{task_id}"
response = requests.get(url, headers=HEADERS)
return response.json()
# Usage example
result = get_screenplay_task_status("ros-sd-20260313-a3f8c2b1")
print(result)
```
### Path Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------ |
| task\_id | string | Yes | The screenplay task ID returned from the [Submit Task](/visual-agents/screenplay/submit-task) endpoint |
### Response
```json Running theme={null}
{
"code": 200,
"msg": "success",
"data": {
"task_id": "ros-sd-20260313-a3f8c2b1",
"status": "running",
"progress": {
"total_episodes": 87,
"completed_episodes": 12
}
},
"failed": false,
"success": true
}
```
```json Completed theme={null}
{
"code": 200,
"msg": "success",
"data": {
"task_id": "ros-sd-20260313-a3f8c2b1",
"status": "completed"
},
"failed": false,
"success": true
}
```
```json Failed theme={null}
{
"code": 200,
"msg": "success",
"data": {
"task_id": "ros-sd-20260313-a3f8c2b1",
"status": "failed",
"error_code": "PROCESSING_FAILED",
"error_message": "Episode 3 processing failed: episode-pipeline ep3 failed: ..."
},
"failed": false,
"success": true
}
```
### Response Parameters
| Parameter | Type | Description |
| --------------------------------- | ------- | ----------------------------------------------------------------- |
| code | integer | Response code indicating the result status |
| msg | string | Response message |
| data.task\_id | string | The screenplay task ID |
| data.status | string | Current task status (see status values below) |
| data.progress | object | Progress information (only present when `status` is `"running"`) |
| data.progress.total\_episodes | integer | Total number of episodes to process |
| data.progress.completed\_episodes | integer | Number of episodes completed so far |
| data.error\_code | string | Error code (only present when `status` is `"failed"`) |
| data.error\_message | string | Detailed error message (only present when `status` is `"failed"`) |
| success | boolean | Indicates whether the API call was successful |
| failed | boolean | Indicates whether the API call failed |
### Task Status Values
| Status | Description |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `pending` | Task has been submitted and is waiting to be processed |
| `running` | Task is currently being processed, check `progress` for details |
| `completed` | Task has finished successfully, use [Download Task Result](/visual-agents/screenplay/download-task-result) to get the output files |
| `failed` | Task has failed, check `error_code` and `error_message` for details |
| `cancelled` | Task has been cancelled via [Cancel Task](/visual-agents/screenplay/cancel-task) |
### Notes
* Poll this endpoint to track progress of long-running tasks
* When status is `"completed"`, use the [Download Task Result](/visual-agents/screenplay/download-task-result) endpoint to download the output files
* The `progress` field is only available when the task is in `"running"` status
## OpenAPI
````yaml GET /screenplay/tasks/{task_id}
openapi: 3.1.0
info:
title: Screenplay Extraction API
description: APIs for screenplay extraction from short drama videos
version: v1.0.0
servers:
- url: https://mavi-backend.memories.ai/serve/api/v2
security:
- ApiKeyAuth: []
paths:
/screenplay/tasks/{task_id}:
get:
summary: Get Task Status
operationId: get_screenplay_task_status
parameters:
- name: task_id
in: path
required: true
schema:
type: string
example: ros-sd-20260313-a3f8c2b1
description: The screenplay task ID
responses:
'200':
description: Task status retrieved successfully
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 200
description: Response code indicating the result status
msg:
type: string
example: success
description: Response message
data:
type: object
properties:
task_id:
type: string
example: ros-sd-20260313-a3f8c2b1
description: The screenplay task ID
status:
type: string
example: running
description: >-
Current task status: pending, running, completed,
failed, cancelled
enum:
- pending
- running
- completed
- failed
- cancelled
progress:
type: object
description: Progress information (only present when running)
properties:
total_episodes:
type: integer
example: 87
description: Total number of episodes to process
completed_episodes:
type: integer
example: 12
description: Number of episodes completed so far
error_code:
type: string
description: Error code (only present when failed)
error_message:
type: string
description: Detailed error message (only present when failed)
success:
type: boolean
example: true
description: Indicates whether the API call was successful
failed:
type: boolean
example: false
description: Indicates whether the API call failed
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: API key for authentication
````