> ## Documentation Index > Fetch the complete documentation index at: https://docs.smooth.sh/llms.txt > Use this file to discover all available pages before exploring further. # Get Task > Returns the status and result of a task by its ID. Use `event_t` parameter for polling to receive only new events since the given timestamp. ## OpenAPI ````yaml /api-reference/openapi.json get /task/{task_id} openapi: 3.1.0 info: title: Smooth version: 0.4.1 description: >- # Introduction The Smooth API allows for programmatic browser automation and task execution. You can run simple one-shot tasks, or create interactive browser sessions for multi-step workflows. This documentation provides a guide to using the API directly, as well as through our Python SDK. # Authentication To use the API, you need an API key. The API key must be sent in the `apikey` header with every request. Example: `apikey: YOUR_API_KEY` If you are using the Python SDK, you can provide the API key in two ways: 1. **Directly in the client constructor**: ```python from smooth import SmoothClient client = SmoothClient(api_key="YOUR_API_KEY") ``` 2. **As an environment variable**: Set the `CIRCLEMIND_API_KEY` environment variable, and the client will automatically use it. ```bash export CIRCLEMIND_API_KEY="YOUR_API_KEY" ``` # Python SDK The Smooth Python SDK provides a convenient way to interact with the Smooth API. ## Installation You can install the Smooth Python SDK using pip: ```bash pip install smooth-py ``` ## Features * **Synchronous and Asynchronous Clients**: Choose between `SmoothClient` for traditional sequential programming and `SmoothAsyncClient` for high-performance asynchronous applications. * **Simple Tasks**: Run one-shot browser automation tasks with `client.run()`. * **Session Workflows**: Create browser sessions for multi-step workflows with `client.session()`. * **Custom Tools**: Register Python functions that the agent can call during execution. ## Usage ### Simple Task Run a one-shot task and wait for the result: ```python from smooth import SmoothClient client = SmoothClient(api_key="YOUR_API_KEY") task_handle = client.run( task="Go to https://www.google.com and search for 'Smooth SDK'" ) print(f"Task started with ID: {task_handle.id()}") print(f"Live view: {task_handle.live_url()}") result = task_handle.result() # Blocks until task is done if result.status == 'done': print("Task Output:", result.output) else: print("Task Failed:", result.output) ``` ### Session Workflow For multi-step workflows, create a session and run multiple actions: ```python from smooth import SmoothClient client = SmoothClient(api_key="YOUR_API_KEY") with client.session(url="https://example.com") as session: # Run a task within the session result = session.run_task("Search for flights from NYC to LA") print(f"Task output: {result.output}") # Extract structured data flights = session.extract( schema={"type": "array", "items": {"type": "object", "properties": {"price": {"type": "number"}}}}, prompt="Extract the first 3 flight prices" ) print(f"Flights: {flights.output}") # Navigate to a URL session.goto("https://example.com/checkout") # Execute JavaScript title = session.evaluate_js("document.title") print(f"Page title: {title.output}") ``` ### Asynchronous Client For async applications: ```python import asyncio from smooth import SmoothAsyncClient async def main(): async with SmoothAsyncClient(api_key="YOUR_API_KEY") as client: task_handle = await client.run( task="Go to Github and search for 'smooth-sdk'" ) print(f"Task started with ID: {task_handle.id()}") result = await task_handle.result() print("Task Output:", result.output) asyncio.run(main()) ``` servers: - url: https://api.smooth.sh/api/v1 security: - APIKeyHeader: [] tags: - name: Task description: Operations for running and managing browser automation tasks - name: Event description: >- Operations for sending events to running tasks (session actions, custom tool responses) - name: Profile description: >- Operations for managing browser profiles (persistent cookies and authentication) - name: File description: Operations for uploading and managing files - name: Extension description: Operations for managing browser extensions paths: /task/{task_id}: get: tags: - Task summary: Get Task description: >- Returns the status and result of a task by its ID. Use `event_t` parameter for polling to receive only new events since the given timestamp. operationId: get_task parameters: - name: task_id in: path required: true schema: type: string title: Task Id - name: event_t in: query required: false schema: type: integer default: 0 description: >- Timestamp of last event received. Only events after this timestamp will be returned. - name: downloads in: query required: false schema: type: boolean default: false description: >- Whether to include the download URL for files downloaded during the task. responses: '200': description: Task has completed (status is 'done', 'failed', or 'cancelled'). content: application/json: schema: $ref: '#/components/schemas/ApiResponse_TaskResponse' '202': description: Task is still running (status is 'waiting' or 'running'). content: application/json: schema: $ref: '#/components/schemas/ApiResponse_TaskResponse' '404': description: Task not found x-codeSamples: - lang: curl label: cURL source: |- curl -X GET "https://api.smooth.sh/api/v1/task/YOUR_TASK_ID" \ -H "apikey: YOUR_API_KEY" - lang: curl label: cURL (polling with event_t) source: >- # Poll for new events since timestamp 1699999999999 curl -X GET "https://api.smooth.sh/api/v1/task/YOUR_TASK_ID?event_t=1699999999999" \ -H "apikey: YOUR_API_KEY" - lang: python label: Python source: |- # The SDK handles polling automatically via task_handle.result() from smooth import SmoothClient client = SmoothClient(api_key="YOUR_API_KEY") task_handle = client.run(task="Go to google.com") # This polls internally until the task completes result = task_handle.result() print(f"Status: {result.status}") print(f"Output: {result.output}") - lang: javascript label: JavaScript source: |- const apiKey = 'YOUR_API_KEY'; const taskId = 'YOUR_TASK_ID'; async function pollTask() { let eventT = 0; while (true) { const response = await fetch( `https://api.smooth.sh/api/v1/task/${taskId}?event_t=${eventT}`, { headers: { 'apikey': apiKey } } ); const data = await response.json(); const task = data.r; if (task.status === 'done' || task.status === 'failed') { console.log('Final output:', task.output); break; } // Update eventT for next poll if (task.events && task.events.length > 0) { eventT = task.events[task.events.length - 1].timestamp; } await new Promise(r => setTimeout(r, 1000)); } } pollTask(); components: schemas: ApiResponse_TaskResponse: type: object properties: r: $ref: '#/components/schemas/TaskResponse' required: - r TaskResponse: type: object properties: id: type: string description: The unique ID of the task. title: ID status: type: string enum: - waiting - running - done - failed - cancelled description: The current status of the task. title: Status output: anyOf: - {} - type: 'null' description: >- The output of the task. If `response_model` was provided, this matches the specified schema. title: Output credits_used: anyOf: - type: integer - type: 'null' description: Number of credits used. 1 credit = $0.01. title: Credits Used device: anyOf: - type: string enum: - desktop - mobile - desktop-lg - type: 'null' description: The device type used for the task. title: Device live_url: anyOf: - type: string - type: 'null' description: URL to view the task execution in real-time. title: Live URL recording_url: anyOf: - type: string - type: 'null' description: >- URL to download the video recording (available after task completes). title: Recording URL downloads_url: anyOf: - type: string - type: 'null' description: URL to download files created during the task. title: Downloads URL created_at: anyOf: - type: integer - type: 'null' description: Unix timestamp when the task was created. title: Created At events: anyOf: - type: array items: $ref: '#/components/schemas/TaskEvent' - type: 'null' description: >- List of new events fired since last poll (when using `event_t` parameter). title: Events required: - id - status title: TaskResponse description: Response model for task operations. TaskEvent: type: object properties: name: type: string description: 'Event type: `browser_action`, `session_action`, or `tool_call`.' title: Name payload: type: object description: >- Event payload. For actions: `{name, input}`. For tool responses: `{code, output}`. title: Payload id: anyOf: - type: string - type: 'null' description: Unique event ID. Used to match responses to requests. title: ID timestamp: anyOf: - type: integer - type: 'null' description: Unix timestamp of the event. title: Timestamp required: - name - payload title: TaskEvent description: Event model for sending actions to running tasks. securitySchemes: APIKeyHeader: type: apiKey in: header name: apikey ````