{ "openapi": "3.1.0", "info": { "title": "Parallel API", "description": "Parallel API", "contact": { "name": "Parallel Support", "url": "https://parallel.ai", "email": "support@parallel.ai" }, "version": "0.1.2" }, "paths": { "/v1/search": { "post": { "tags": [ "Search" ], "summary": "Search", "description": "Searches the web.\n\nThe legacy Search API reference (`/v1beta/search` endpoint) is available\n[here](https://docs.parallel.ai/api-reference/legacy/search-beta/search), and\nmigration guide is [here](https://docs.parallel.ai/search/search-migration-guide).", "operationId": "v1_search_v1_search_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1SearchRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1SearchResponse" }, "example": { "search_id": "search_fcb2b4f3c75e418687bccaa1a8381331", "results": [ { "url": "https://www.example.com", "title": "Sample webpage title", "publish_date": "2024-01-15", "excerpts": [ "Sample excerpt 1", "Sample excerpt 2" ] } ], "session_id": "session_fcb2b4f3c75e418687bccaa1a8381331" } } } }, "422": { "description": "Request validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "type": "error", "error": { "ref_id": "search_fcb2b4f3c75e418687bccaa1a8381331", "message": "Request validation error" } } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\nsearch = client.search(\n objective=\"Find latest information about Parallel Web Systems. Focus on new product releases, benchmarks, or company announcements.\",\n search_queries=[\"Parallel Web Systems products\", \"Parallel Web Systems announcements\"],\n)\nprint(search.results)" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst search = await client.search({\n objective: \"Find latest information about Parallel Web Systems. Focus on new product releases, benchmarks, or company announcements.\",\n search_queries: [\"Parallel Web Systems products\", \"Parallel Web Systems announcements\"],\n});\nconsole.log(search.results);" }, { "lang": "cURL", "source": "curl --request POST \\\n --url https://api.parallel.ai/v1/search \\\n --header 'Content-Type: application/json' \\\n --header 'x-api-key: ' \\\n --data '{\n \"objective\": \"Find latest information about Parallel Web Systems. Focus on new product releases, benchmarks, or company announcements.\",\n \"search_queries\": [\"Parallel Web Systems products\", \"Parallel Web Systems announcements\"]\n}'" } ] } }, "/v1/extract": { "post": { "tags": [ "Extract" ], "summary": "Extract", "description": "Extracts relevant content from specific web URLs.\n\nThe legacy Extract API reference (`/v1beta/extract` endpoint) is available\n[here](https://docs.parallel.ai/api-reference/legacy/extract-beta/extract), and\nmigration guide is [here](https://docs.parallel.ai/extract/extract-migration-guide).", "operationId": "extract_v1_extract_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ExtractRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ExtractResponse" }, "example": { "extract_id": "extract_8a911eb27c7a4afaa20d0d9dc98d07c0", "results": [ { "url": "https://www.example.com", "title": "Example Title", "excerpts": [ "Excerpted text ..." ], "full_content": "Full content ..." } ], "errors": [ { "url": "https://www.example.com", "error_type": "fetch_error", "http_status_code": 500, "content": "Error fetching content from https://www.example.com" } ], "session_id": "session_8a911eb27c7a4afaa20d0d9dc98d07c0" } } } }, "422": { "description": "Request validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "type": "error", "error": { "ref_id": "extract_8a911eb27c7a4afaa20d0d9dc98d07c0", "message": "Request validation error" } } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\nextract = client.extract(\n urls=[\"https://www.example.com\"],\n objective=\"Summarize the page\",\n)\nprint(extract.results)" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst extract = await client.extract({\n urls: [\"https://www.example.com\"],\n objective: \"Summarize the page\",\n});\nconsole.log(extract.results);" }, { "lang": "cURL", "source": "curl --request POST \\\n --url https://api.parallel.ai/v1/extract \\\n --header 'Content-Type: application/json' \\\n --header 'x-api-key: ' \\\n --data '{\n \"urls\": [\"https://www.example.com\"],\n \"objective\": \"Summarize the page\"\n}'" } ] } }, "/v1/tasks/groups": { "post": { "tags": [ "Tasks" ], "summary": "Create Task Group", "description": "Initiates a TaskGroup to group and track multiple runs.", "operationId": "tasks_taskgroups_post_v1_tasks_groups_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTaskGroupRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskGroupResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\ntask_group = client.task_group.create(metadata={\"key\": \"value\"})\nprint(task_group.task_group_id)" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst taskGroup = await client.taskGroup.create({\n metadata: {'key': 'value'},\n});\nconsole.log(taskGroup.taskgroup_id);" } ] } }, "/v1/tasks/groups/{taskgroup_id}": { "get": { "tags": [ "Tasks" ], "summary": "Retrieve Task Group", "description": "Retrieves aggregated status across runs in a TaskGroup.", "operationId": "tasks_taskgroups_get_v1_tasks_groups__taskgroup_id__get", "parameters": [ { "name": "taskgroup_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Taskgroup Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskGroupResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\ntask_group = client.task_group.retrieve(\"taskgroup_id\")\nprint(task_group.status)" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst taskGroup = await client.taskGroup.retrieve(\n 'taskgroup_id',\n);\nconsole.log(taskGroup.status);" } ] } }, "/v1/tasks/groups/{taskgroup_id}/events": { "get": { "tags": [ "Tasks" ], "summary": "Stream Task Group Events", "description": "Streams events from a TaskGroup: status updates and run completions.\n\nThe connection will remain open for up to an hour as long as at least one run in the\ngroup is still active.", "operationId": "tasks_sessions_events_get_v1_tasks_groups__taskgroup_id__events_get", "parameters": [ { "name": "taskgroup_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Taskgroup Id" } }, { "name": "last_event_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Event Id" } }, { "name": "timeout", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Timeout" } } ], "responses": { "200": { "description": "Successful Response", "content": { "text/event-stream": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TaskGroupStatusEvent" }, { "$ref": "#/components/schemas/TaskRunEvent" }, { "$ref": "#/components/schemas/ErrorEvent" } ], "discriminator": { "propertyName": "type", "mapping": { "task_group_status": "#/components/schemas/TaskGroupStatusEvent", "task_run.state": "#/components/schemas/TaskRunEvent", "error": "#/components/schemas/ErrorEvent" } }, "title": "Response 200 Tasks Sessions Events Get V1 Tasks Groups Taskgroup Id Events Get" }, "example": { "type": "task_group_status", "event_id": "123", "status": { "num_task_runs": 1, "task_run_status_counts": { "completed": 1 }, "is_active": false, "status_message": "", "modified_at": "2025-04-23T20:21:48.037943Z" } } } } }, "404": { "description": "TaskGroup not found", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "TaskGroup not found" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\ntask_group_events = client.task_group.events(\"taskgroup_id\")\nfor event in task_group_events:\n print(event)\n" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst taskGroupEvents = await client.taskGroup.events(\n 'taskgroup_id',\n);\nfor await (const event of taskGroupEvents) {\n console.log(event);\n}\n" } ] } }, "/v1/tasks/groups/{taskgroup_id}/runs": { "post": { "tags": [ "Tasks" ], "summary": "Add Runs to Task Group", "description": "Initiates multiple task runs within a TaskGroup.", "operationId": "tasks_taskgroups_runs_post_v1_tasks_groups__taskgroup_id__runs_post", "parameters": [ { "name": "taskgroup_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Taskgroup Id" } }, { "name": "refresh_status", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Refresh Status" } }, { "name": "parallel-beta", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parallel-Beta", "x-stainless-override-schema": { "x-stainless-param": "betas", "x-stainless-extend-default": true, "type": "array", "description": "Optional header to specify the beta version(s) to enable.", "items": { "$ref": "#/components/schemas/ParallelBeta" } } } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskGroupRunRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskGroupRunResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\nfrom parallel.types import McpServerParam\nfrom parallel.types.run_input_param import RunInputParam\n\nclient = Parallel(api_key=\"API Key\")\ngroup_status = client.task_group.add_runs(\n \"taskgroup_id\",\n inputs=[\n RunInputParam(\n input=\"What was the GDP of France in 2023?\",\n processor=\"base\",\n enable_events=True,\n mcp_servers=[McpServerParam(\n type=\"url\",\n name=\"parallel_web_search\",\n url=\"https://mcp.parallel.ai/v1beta/search_mcp\",\n headers={\"x-api-key\": \"API Key\"}\n )]\n )\n ]\n)\nprint(group_status.status)\n" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst groupStatus = await client.taskGroup.addRuns(\n 'taskgroup_id',\n {\n inputs: [\n {\n input: 'What was the GDP of France in 2023?',\n processor: 'base',\n enable_events: true,\n mcp_servers: [{\n type: 'url',\n name: 'parallel_web_search',\n url: 'https://mcp.parallel.ai/v1beta/search_mcp',\n headers: {'x-api-key': 'API Key'}\n }]\n }\n ]\n }\n);\nconsole.log(groupStatus.status);" } ] }, "get": { "tags": [ "Tasks" ], "summary": "Fetch Task Group Runs", "description": "Retrieves task runs in a TaskGroup and optionally their inputs and outputs.\n\nAll runs within a TaskGroup are returned as a stream. To get the inputs and/or\noutputs back in the stream, set the corresponding `include_input` and\n`include_output` parameters to `true`.\n\nThe stream is resumable using the `event_id` as the cursor. To resume a stream,\nspecify the `last_event_id` parameter with the `event_id` of the last event in the\nstream. The stream will resume from the next event after the `last_event_id`.", "operationId": "tasks_taskgroups_runs_get_v1_tasks_groups__taskgroup_id__runs_get", "parameters": [ { "name": "taskgroup_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Taskgroup Id" } }, { "name": "last_event_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Event Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "queued", "action_required", "running", "completed", "failed", "cancelling", "cancelled" ], "type": "string" }, { "type": "null" } ], "title": "Status" } }, { "name": "include_input", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Input" } }, { "name": "include_output", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Output" } } ], "responses": { "200": { "description": "Successful Response", "content": { "text/event-stream": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TaskRunEvent" }, { "$ref": "#/components/schemas/ErrorEvent" } ], "discriminator": { "propertyName": "type", "mapping": { "task_run.state": "#/components/schemas/TaskRunEvent", "error": "#/components/schemas/ErrorEvent" } }, "title": "Response 200 Tasks Taskgroups Runs Get V1 Tasks Groups Taskgroup Id Runs Get" }, "example": { "type": "task_run.state", "event_id": "123", "input": { "processor": "core", "metadata": { "my_key": "my_value" }, "input": { "country": "France", "year": 2023 } }, "run": { "run_id": "trun_9907962f83aa4d9d98fd7f4bf745d654", "interaction_id": "trun_9907962f83aa4d9d98fd7f4bf745d654", "status": "completed", "is_active": false, "processor": "core", "metadata": { "my_key": "my_value" }, "created_at": "2025-04-23T20:21:48.037943Z", "modified_at": "2025-04-23T20:21:48.037943Z" } } } } }, "404": { "description": "TaskGroup not found", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "TaskGroup not found" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\ntask_group_runs = client.task_group.get_runs(\"taskgroup_id\")\nfor run in task_group_runs:\n print(run)\n" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst taskGroupRuns = await client.taskGroup.getRuns(\n 'taskgroup_id',\n);\nfor await (const run of taskGroupRuns) {\n console.log(run);\n}\n" } ] } }, "/v1/tasks/groups/{taskgroup_id}/runs/{run_id}": { "get": { "tags": [ "Tasks" ], "summary": "Retrieve Task Group Run", "description": "Retrieves run status by run_id.\n\nThis endpoint is equivalent to fetching run status directly using the\n`retrieve()` method or the `tasks/runs` GET endpoint.\n\nThe run result is available from the `/result` endpoint.", "operationId": "tasks_taskgroups_runs_id_get_v1_tasks_groups__taskgroup_id__runs__run_id__get", "parameters": [ { "name": "taskgroup_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Taskgroup Id" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRun" }, "example": { "run_id": "trun_9907962f83aa4d9d98fd7f4bf745d654", "interaction_id": "trun_9907962f83aa4d9d98fd7f4bf745d654", "status": "running", "is_active": true, "processor": "core", "metadata": { "my_key": "my_value" }, "created_at": "2025-04-23T20:21:48.037943Z", "modified_at": "2025-04-23T20:21:48.037943Z" } } } }, "401": { "description": "Unauthorized: invalid or missing credentials", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unauthorized: invalid or missing credentials" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Run id not found", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Run id not found" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation error", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Request validation error" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\ntask_run = client.task_run.retrieve(\"run_id\")\nprint(task_run.status)" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst taskRun = await client.taskRun.retrieve('run_id');\nconsole.log(taskRun.status);" } ] } }, "/v1/tasks/runs": { "post": { "tags": [ "Tasks" ], "summary": "Create Task Run", "description": "Initiates a task run.\n\nReturns immediately with a run object in status 'queued'.\n\nBeta features can be enabled by setting the 'parallel-beta' header.", "operationId": "tasks_runs_post_v1_tasks_runs_post", "parameters": [ { "name": "parallel-beta", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parallel-Beta", "x-stainless-override-schema": { "x-stainless-param": "betas", "x-stainless-extend-default": true, "type": "array", "description": "Optional header to specify the beta version(s) to enable.", "items": { "$ref": "#/components/schemas/ParallelBeta" } } } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRunInput" } } } }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRun" }, "example": { "run_id": "trun_9907962f83aa4d9d98fd7f4bf745d654", "interaction_id": "trun_9907962f83aa4d9d98fd7f4bf745d654", "status": "queued", "is_active": true, "processor": "core", "metadata": { "my_key": "my_value" }, "created_at": "2025-04-23T20:21:48.037943Z", "modified_at": "2025-04-23T20:21:48.037943Z" } } } }, "401": { "description": "Unauthorized: invalid or missing credentials", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unauthorized: invalid or missing credentials" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required: insufficient credit in account", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Payment required: insufficient credit in account" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden: invalid processor in request", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Forbidden: invalid processor in request" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content: request validation error", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unprocessable content: request validation error" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests: quota temporarily exceeded", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Too many requests: quota temporarily exceeded" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\ntask_run = client.task_run.create(\n input=\"What was the GDP of France in 2023?\",\n processor=\"base\",\n)\nprint(task_run.run_id)" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst taskRun = await client.taskRun.create({\n input: 'What was the GDP of France in 2023?',\n processor: 'base',\n});\nconsole.log(taskRun.run_id);" } ] } }, "/v1/tasks/runs/{run_id}": { "get": { "tags": [ "Tasks" ], "summary": "Retrieve Task Run", "description": "Retrieves run status by run_id.\n\nThe run result is available from the `/result` endpoint.", "operationId": "tasks_runs_get_v1_tasks_runs__run_id__get", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRun" }, "example": { "run_id": "trun_9907962f83aa4d9d98fd7f4bf745d654", "interaction_id": "trun_9907962f83aa4d9d98fd7f4bf745d654", "status": "running", "is_active": true, "processor": "core", "metadata": { "my_key": "my_value" }, "created_at": "2025-04-23T20:21:48.037943Z", "modified_at": "2025-04-23T20:21:48.037943Z" } } } }, "401": { "description": "Unauthorized: invalid or missing credentials", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unauthorized: invalid or missing credentials" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Run id not found", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Run id not found" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation error", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Request validation error" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\ntask_run = client.task_run.retrieve(\"run_id\")\nprint(task_run.status)" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst taskRun = await client.taskRun.retrieve('run_id');\nconsole.log(taskRun.status);" } ] } }, "/v1/tasks/runs/{run_id}/events": { "get": { "tags": [ "Tasks" ], "summary": "Stream Task Run Events", "description": "Streams events for a task run.\n\nReturns a stream of events showing progress updates and state changes for the task\nrun.\n\nFor task runs that did not have enable_events set to true during creation, the\nfrequency of events will be reduced.", "operationId": "tasks_runs_events_get_v1_tasks_runs__run_id__events_get", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "text/event-stream": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TaskRunProgressStatsEvent" }, { "$ref": "#/components/schemas/TaskRunProgressMessageEvent" }, { "$ref": "#/components/schemas/TaskRunEvent" }, { "$ref": "#/components/schemas/ErrorEvent" } ], "discriminator": { "propertyName": "type", "mapping": { "task_run.progress_stats": "#/components/schemas/TaskRunProgressStatsEvent", "task_run.progress_msg.plan": "#/components/schemas/TaskRunProgressMessageEvent", "task_run.progress_msg.search": "#/components/schemas/TaskRunProgressMessageEvent", "task_run.progress_msg.result": "#/components/schemas/TaskRunProgressMessageEvent", "task_run.progress_msg.tool_call": "#/components/schemas/TaskRunProgressMessageEvent", "task_run.progress_msg.exec_status": "#/components/schemas/TaskRunProgressMessageEvent", "task_run.state": "#/components/schemas/TaskRunEvent", "error": "#/components/schemas/ErrorEvent" } }, "title": "Response 200 Tasks Runs Events Get V1 Tasks Runs Run Id Events Get" }, "example": { "type": "task_run.progress_msg.plan", "message": "Planning task...", "timestamp": "2025-04-23T20:21:48.037943Z" } } } }, "401": { "description": "Unauthorized: invalid or missing credentials", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unauthorized: invalid or missing credentials" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Run id not found", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Run id not found" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation error", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Request validation error" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\nevents = client.task_run.events(run_id=\"run_id\")\nfor event in events:\n print(event)\n" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst events = await client.taskRun.events(\n 'run_id',\n);\nfor await (const event of events) {\n console.log(event);\n}\n" } ] } }, "/v1/tasks/runs/{run_id}/input": { "get": { "tags": [ "Tasks" ], "summary": "Retrieve Task Run Input", "description": "Retrieves the input of a run by run_id.", "operationId": "tasks_runs_input_get_v1_tasks_runs__run_id__input_get", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRunInput" }, "example": { "processor": "core", "metadata": { "my_key": "my_value" }, "task_spec": { "output_schema": { "json_schema": { "type": "object", "properties": { "gdp": { "type": "string", "description": "GDP in USD for the year, formatted like '$3.1 trillion (2023)'" } }, "required": [ "gdp" ], "additionalProperties": false }, "type": "json" }, "input_schema": { "json_schema": { "type": "object", "properties": { "country": { "type": "string" }, "year": { "type": "integer" } }, "required": [ "country", "year" ], "additionalProperties": false }, "type": "json" } }, "input": { "country": "France", "year": 2023 } } } } }, "401": { "description": "Unauthorized: invalid or missing credentials", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unauthorized: invalid or missing credentials" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Run id not found", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Run id not found" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation error", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Request validation error" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/tasks/runs/{run_id}/result": { "get": { "tags": [ "Tasks" ], "summary": "Retrieve Task Run Result", "description": "Retrieves a run result by run_id, blocking until the run is completed.", "operationId": "tasks_runs_result_get_v1_tasks_runs__run_id__result_get", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } }, { "name": "timeout", "in": "query", "required": false, "schema": { "type": "integer", "default": 600, "title": "Timeout" } }, { "name": "parallel-beta", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parallel-Beta", "x-stainless-override-schema": { "x-stainless-param": "betas", "x-stainless-extend-default": true, "type": "array", "description": "Optional header to specify the beta version(s) to enable.", "items": { "$ref": "#/components/schemas/ParallelBeta" } } } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskRunResult" }, "example": { "run": { "run_id": "trun_9907962f83aa4d9d98fd7f4bf745d654", "interaction_id": "trun_9907962f83aa4d9d98fd7f4bf745d654", "status": "completed", "is_active": false, "processor": "core", "metadata": { "my_key": "my_value" }, "created_at": "2025-04-23T20:21:48.037943Z", "modified_at": "2025-04-23T20:21:48.037943Z" }, "output": { "basis": [], "type": "json", "content": { "gdp": "$3.1 trillion (2023)" } } } } } }, "401": { "description": "Unauthorized: invalid or missing credentials", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unauthorized: invalid or missing credentials" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Run failed or run id not found", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Run failed or run id not found" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "408": { "description": "Request timed out; run still active", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Request timed out; run still active" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation error", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Request validation error" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\ntask_run_result = client.task_run.result(run_id=\"run_id\")\nprint(task_run_result.output)" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst taskRunResult = await client.taskRun.result('run_id');\nconsole.log(taskRunResult.output);" } ] } }, "/v1beta/tasks/runs/{run_id}/events": { "get": { "tags": [ "Tasks" ], "summary": "Stream Task Run Events", "description": "Streams events for a task run.\n\nReturns a stream of events showing progress updates and state changes for the task\nrun.\n\nFor task runs that did not have enable_events set to true during creation, the\nfrequency of events will be reduced.", "operationId": "tasks_runs_events_get_v1beta_tasks_runs__run_id__events_get", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "text/event-stream": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TaskRunProgressStatsEvent" }, { "$ref": "#/components/schemas/TaskRunProgressMessageEvent" }, { "$ref": "#/components/schemas/TaskRunEvent" }, { "$ref": "#/components/schemas/ErrorEvent" } ], "discriminator": { "propertyName": "type", "mapping": { "task_run.progress_stats": "#/components/schemas/TaskRunProgressStatsEvent", "task_run.progress_msg.plan": "#/components/schemas/TaskRunProgressMessageEvent", "task_run.progress_msg.search": "#/components/schemas/TaskRunProgressMessageEvent", "task_run.progress_msg.result": "#/components/schemas/TaskRunProgressMessageEvent", "task_run.progress_msg.tool_call": "#/components/schemas/TaskRunProgressMessageEvent", "task_run.progress_msg.exec_status": "#/components/schemas/TaskRunProgressMessageEvent", "task_run.state": "#/components/schemas/TaskRunEvent", "error": "#/components/schemas/ErrorEvent" } }, "title": "Response 200 Tasks Runs Events Get V1Beta Tasks Runs Run Id Events Get" }, "example": { "type": "task_run.progress_msg.plan", "message": "Planning task...", "timestamp": "2025-04-23T20:21:48.037943Z" } } } }, "401": { "description": "Unauthorized: invalid or missing credentials", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unauthorized: invalid or missing credentials" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Run id not found", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Run id not found" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation error", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Request validation error" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\nevents = client.beta.task_run.events(run_id=\"run_id\")\nfor event in events:\n print(event)\n" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst events = await client.beta.taskRun.events(\n 'run_id',\n);\nfor await (const event of events) {\n console.log(event);\n}\n" } ] } }, "/v1beta/findall/entity-search": { "post": { "tags": [ "FindAll" ], "summary": "Fast Entity Search", "description": "Return ranked entities matching a natural language objective.\n\nThis endpoint performs a best-effort search optimized for low latency. To keep\nresponses fast, it returns a fixed set of attributes and supports queries of\nlimited complexity.\n\nFor comprehensive match evaluation and enrichment, use the\n[FindAll API](https://docs.parallel.ai/findall-api/findall-quickstart).", "operationId": "findall_entity_search_v1beta_findall_entity_search_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindAllEntitySearchRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindAllEntitySearchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\nresponse = client.beta.findall.entity_search(\n entity_type=\"companies\",\n objective=\"AI startups that raised Series A in 2024\",\n match_limit=100,\n)\n\nfor entity in response.entities:\n print(f\"{entity.name}: {entity.url}\")" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst response = await client.beta.findall.entity_search({\n entity_type: \"companies\",\n objective: \"AI startups that raised Series A in 2024\",\n match_limit: 100,\n});\n\nfor (const entity of response.entities) {\n console.log(`${entity.name}: ${entity.url}`);\n}" } ] } }, "/v1beta/findall/ingest": { "post": { "tags": [ "FindAll" ], "summary": "Ingest FindAll Run", "description": "Transforms a natural language search objective into a structured FindAll spec.\n\nThe generated specification serves as a suggested starting point and can be further\ncustomized by the user.", "operationId": "ingest_findall_run_v1beta_findall_ingest_post", "parameters": [ { "name": "parallel-beta", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "deprecated": true, "title": "Parallel-Beta", "x-stainless-override-schema": { "x-stainless-param": "betas", "x-stainless-extend-default": true, "type": "array", "description": "Optional header to specify the beta version(s) to enable.", "items": { "$ref": "#/components/schemas/ParallelBeta" } } }, "deprecated": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindAllSchema" }, "example": { "objective": "Find all AI companies that raised Series A funding in 2024", "entity_type": "companies", "match_conditions": [ { "name": "developing_ai_products_check", "description": "Company must be developing artificial intelligence (AI) products" }, { "name": "raised_series_a_2024_check", "description": "Company must have raised Series A funding in 2024" } ], "generator": "core" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\nobjective = \"Find all portfolio companies of Khosla Ventures founded after 2020 and CEO names\"\n\ningest = client.beta.findall.ingest(\n objective=objective,\n)\n\nprint(ingest.model_dump_json(indent=2))" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst objective = 'Find all portfolio companies of Khosla Ventures founded after 2020 and CEO names';\n\nconst ingest = await client.beta.findall.ingest({\n objective: objective,\n});\n\nconsole.log(JSON.stringify(ingest, null, 2));" } ] } }, "/v1beta/findall/runs": { "post": { "tags": [ "FindAll" ], "summary": "Create FindAll Run", "description": "Starts a FindAll run.\n\nThis endpoint immediately returns a FindAll run object with status set to 'queued'.\nYou can get the run result snapshot using the GET /v1beta/findall/runs/{findall_id}/result endpoint.\nYou can track the progress of the run by:\n- Polling the status using the GET /v1beta/findall/runs/{findall_id} endpoint,\n- Subscribing to real-time updates via the /v1beta/findall/runs/{findall_id}/events\nendpoint,\n- Or specifying a webhook with relevant event types during run creation to receive\nnotifications.", "operationId": "findall_runs_v1_v1beta_findall_runs_post", "parameters": [ { "name": "parallel-beta", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "deprecated": true, "title": "Parallel-Beta", "x-stainless-override-schema": { "x-stainless-param": "betas", "x-stainless-extend-default": true, "type": "array", "description": "Optional header to specify the beta version(s) to enable.", "items": { "$ref": "#/components/schemas/ParallelBeta" } } }, "deprecated": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindAllRunInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindAllRun" }, "example": { "findall_id": "findall_56ccc4d188fb41a0803a935cf485c774", "status": { "status": "queued", "is_active": true, "metrics": { "generated_candidates_count": 0, "matched_candidates_count": 0 } }, "generator": "base", "metadata": {}, "created_at": "2025-09-10T21:02:08.626446Z", "modified_at": "2025-09-10T21:02:08.627376Z" } } } }, "402": { "description": "Payment required: insufficient credit in account", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Payment required: insufficient credit in account" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content: request validation error", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unprocessable content: request validation error" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests: quota temporarily exceeded", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Too many requests: quota temporarily exceeded" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\n# Use the output from the ingest step, or provide your own values\ningest = client.beta.findall.ingest(\n objective=\"Find all AI companies that raised Series A funding in 2024\",\n)\n\nrun = client.beta.findall.create(\n objective=ingest.objective,\n entity_type=ingest.entity_type,\n match_conditions=[mc.model_dump() for mc in ingest.match_conditions],\n generator=\"base\",\n match_limit=10,\n)\n\nprint(f\"FindAll run {run.findall_id} created, response:\")\nprint(run.model_dump_json(indent=2))" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\n// Use the output from the ingest step, or provide your own values\nconst ingest = await client.beta.findall.ingest({\n objective: \"Find all AI companies that raised Series A funding in 2024\",\n});\n\nconst run = await client.beta.findall.create({\n objective: ingest.objective,\n entity_type: ingest.entity_type,\n match_conditions: ingest.match_conditions,\n generator: \"base\",\n match_limit: 10,\n});\n\nconsole.log(`FindAll run ${run.findall_id} created, response:`);\nconsole.log(JSON.stringify(run, null, 2));" } ] } }, "/v1beta/findall/runs/{findall_id}": { "get": { "tags": [ "FindAll" ], "summary": "Retrieve FindAll Run Status", "description": "Retrieve a FindAll run.", "operationId": "findall_runs_v1_get_v1beta_findall_runs__findall_id__get", "parameters": [ { "name": "findall_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Findall Id" } }, { "name": "parallel-beta", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "deprecated": true, "title": "Parallel-Beta", "x-stainless-override-schema": { "x-stainless-param": "betas", "x-stainless-extend-default": true, "type": "array", "description": "Optional header to specify the beta version(s) to enable.", "items": { "$ref": "#/components/schemas/ParallelBeta" } } }, "deprecated": true } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindAllRun" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\nrun = client.beta.findall.retrieve(\n findall_id=\"findall_56ccc4d188fb41a0803a935cf485c774\",\n)\n\nprint(f\"FindAll run {run.findall_id} status: {run.status.status}\")" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst run = await client.beta.findall.retrieve(\"findall_56ccc4d188fb41a0803a935cf485c774\");\n\nconsole.log(`FindAll run ${run.findall_id} status: ${run.status.status}`);" } ] } }, "/v1beta/findall/runs/{findall_id}/cancel": { "post": { "tags": [ "FindAll" ], "summary": "Cancel FindAll Run", "description": "Cancel a FindAll run.", "operationId": "cancel_findall_run_v1beta_findall_runs__findall_id__cancel_post", "parameters": [ { "name": "findall_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Findall Id" } }, { "name": "parallel-beta", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "deprecated": true, "title": "Parallel-Beta", "x-stainless-override-schema": { "x-stainless-param": "betas", "x-stainless-extend-default": true, "type": "array", "description": "Optional header to specify the beta version(s) to enable.", "items": { "$ref": "#/components/schemas/ParallelBeta" } } }, "deprecated": true } ], "responses": { "204": { "description": "FindAll run cancelled successfully." }, "404": { "description": "FindAll run not found", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "FindAll run not found" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Cannot cancel a terminated FindAll run", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Cannot cancel a terminated FindAll run" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\nclient.beta.findall.cancel(\n findall_id=\"findall_56ccc4d188fb41a0803a935cf485c774\",\n)\n\nprint(\"FindAll run cancelled.\")" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nawait client.beta.findall.cancel(\"findall_56ccc4d188fb41a0803a935cf485c774\");\n\nconsole.log(\"FindAll run cancelled.\");" } ] } }, "/v1beta/findall/runs/{findall_id}/enrich": { "post": { "tags": [ "FindAll" ], "summary": "Add Enrichment to FindAll Run", "description": "Add an enrichment to a FindAll run.", "operationId": "enrich_findall_run_v1beta_findall_runs__findall_id__enrich_post", "parameters": [ { "name": "findall_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Findall Id" } }, { "name": "parallel-beta", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "deprecated": true, "title": "Parallel-Beta", "x-stainless-override-schema": { "x-stainless-param": "betas", "x-stainless-extend-default": true, "type": "array", "description": "Optional header to specify the beta version(s) to enable.", "items": { "$ref": "#/components/schemas/ParallelBeta" } } }, "deprecated": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindAllEnrichInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindAllSchema" }, "example": { "objective": "Find all AI companies that raised Series A funding in 2024", "entity_type": "companies", "match_conditions": [ { "name": "developing_ai_products_check", "description": "Company must be developing artificial intelligence (AI) products" } ], "enrichments": [ { "processor": "core", "output_schema": { "json_schema": { "type": "object", "properties": { "ceo_name": { "type": "string", "description": "Name of the current CEO of the company. If the CEO is not publicly known, provide the name of the highest-ranking executive or founder. If no information is available, return null." } } }, "type": "json" } } ], "generator": "core", "match_limit": 50 } } } }, "404": { "description": "FindAll run not found", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "FindAll run not found" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Validation error" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\n# Tip: If using Pydantic models, you can generate the schema automatically:\n# class CompanyEnrichment(BaseModel):\n# ceo_name: str = Field(description=\"Name of the CEO\")\n# founding_year: str = Field(description=\"Year the company was founded\")\n# output_schema = {\"type\": \"json\", \"json_schema\": CompanyEnrichment.model_json_schema()}\n\nschema = client.beta.findall.enrich(\n findall_id=\"findall_40e0ab8c10754be0b7a16477abb38a2f\",\n processor=\"core\",\n output_schema={\n \"type\": \"json\",\n \"json_schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"ceo_name\": {\n \"type\": \"string\",\n \"description\": \"Name of the CEO\"\n },\n \"founding_year\": {\n \"type\": \"string\",\n \"description\": \"Year the company was founded\"\n }\n },\n \"required\": [\"ceo_name\", \"founding_year\"],\n \"additionalProperties\": False\n }\n }\n)\n\nprint(f\"Enrichment added, schema: {schema.model_dump_json(indent=2)}\")" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst schema = await client.beta.findall.enrich(\n \"findall_40e0ab8c10754be0b7a16477abb38a2f\",\n {\n processor: \"core\",\n output_schema: {\n type: \"json\",\n json_schema: {\n type: \"object\",\n properties: {\n ceo_name: {\n type: \"string\",\n description: \"Name of the CEO\"\n },\n founding_year: {\n type: \"string\",\n description: \"Year the company was founded\"\n }\n },\n required: [\"ceo_name\", \"founding_year\"],\n additionalProperties: false\n }\n }\n }\n);\n\nconsole.log(`Enrichment added, schema: ${JSON.stringify(schema, null, 2)}`);" } ] } }, "/v1beta/findall/runs/{findall_id}/events": { "get": { "tags": [ "FindAll" ], "summary": "Stream FindAll Events", "description": "Stream events from a FindAll run.\n\nArgs:\n request: The Shapi request\n findall_id: The FindAll run ID\n last_event_id: Optional event ID to resume from.\n timeout: Optional timeout in seconds. If None, keep connection alive\n as long as the run is going. If set, stop after specified duration.", "operationId": "get_findall_events_v1beta_findall_runs__findall_id__events_get", "parameters": [ { "name": "findall_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Findall Id" } }, { "name": "last_event_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Event Id" } }, { "name": "timeout", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Timeout" } }, { "name": "parallel-beta", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "deprecated": true, "title": "Parallel-Beta", "x-stainless-override-schema": { "x-stainless-param": "betas", "x-stainless-extend-default": true, "type": "array", "description": "Optional header to specify the beta version(s) to enable.", "items": { "$ref": "#/components/schemas/ParallelBeta" } } }, "deprecated": true } ], "responses": { "200": { "description": "Successful Response", "content": { "text/event-stream": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/FindAllSchemaUpdatedEvent" }, { "$ref": "#/components/schemas/FindAllRunStatusEvent" }, { "$ref": "#/components/schemas/FindAllCandidateMatchStatusEvent" }, { "$ref": "#/components/schemas/ErrorEvent" } ], "discriminator": { "propertyName": "type", "mapping": { "findall.schema.updated": "#/components/schemas/FindAllSchemaUpdatedEvent", "findall.status": "#/components/schemas/FindAllRunStatusEvent", "findall.candidate.generated": "#/components/schemas/FindAllCandidateMatchStatusEvent", "findall.candidate.matched": "#/components/schemas/FindAllCandidateMatchStatusEvent", "findall.candidate.unmatched": "#/components/schemas/FindAllCandidateMatchStatusEvent", "findall.candidate.discarded": "#/components/schemas/FindAllCandidateMatchStatusEvent", "findall.candidate.enriched": "#/components/schemas/FindAllCandidateMatchStatusEvent", "error": "#/components/schemas/ErrorEvent" } }, "title": "Response 200 Get Findall Events V1Beta Findall Runs Findall Id Events Get" }, "example": { "type": "findall.candidate.generated", "timestamp": "2025-09-10T21:02:08.626446Z", "event_id": "56cee734dbc84172bfc491327f2a0183", "data": { "candidate_id": "candidate_52e1e30b-4e0a-49d8-82eb-79e64e0ed015", "name": "Pika", "url": "pika.art", "description": "Pika is an AI video generation platform that creates and edits videos from text prompts or images.", "match_status": "generated" } } } } }, "404": { "description": "FindAll run not found", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "FindAll run not found" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\n# Event types: findall.candidate.generated, findall.candidate.matched,\n# findall.candidate.unmatched, findall.candidate.discarded,\n# findall.candidate.enriched\nevents = client.beta.findall.events(\n findall_id=\"findall_56ccc4d188fb41a0803a935cf485c774\",\n)\n\nfor event in events:\n print(f\"Event [{event.type}]: {event.model_dump_json()}\")" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\n// Event types: findall.candidate.generated, findall.candidate.matched,\n// findall.candidate.unmatched, findall.candidate.discarded,\n// findall.candidate.enriched\nconst events = await client.beta.findall.events(\"findall_56ccc4d188fb41a0803a935cf485c774\");\n\nfor await (const event of events) {\n console.log(`Event [${event.type}]: ${JSON.stringify(event)}`);\n}" } ] } }, "/v1beta/findall/runs/{findall_id}/extend": { "post": { "tags": [ "FindAll" ], "summary": "Extend FindAll Run", "description": "Extend a FindAll run by adding additional matches to the current match limit.", "operationId": "extend_findall_run_v1beta_findall_runs__findall_id__extend_post", "parameters": [ { "name": "findall_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Findall Id" } }, { "name": "parallel-beta", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "deprecated": true, "title": "Parallel-Beta", "x-stainless-override-schema": { "x-stainless-param": "betas", "x-stainless-extend-default": true, "type": "array", "description": "Optional header to specify the beta version(s) to enable.", "items": { "$ref": "#/components/schemas/ParallelBeta" } } }, "deprecated": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindAllExtendInput" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindAllSchema" }, "example": { "objective": "Find all AI companies that raised Series A funding in 2024", "entity_type": "companies", "match_conditions": [ { "name": "developing_ai_products_check", "description": "Company must be developing artificial intelligence (AI) products" } ], "enrichments": [ { "processor": "core", "output_schema": { "json_schema": { "type": "object", "properties": { "ceo_name": { "type": "string", "description": "Name of the current CEO of the company. If the CEO is not publicly known, provide the name of the highest-ranking executive or founder. If no information is available, return null." } } }, "type": "json" } } ], "generator": "core", "match_limit": 50 } } } }, "404": { "description": "FindAll run not found", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "FindAll run not found" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Additional match limit must be greater than 0", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Additional match limit must be greater than 0" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\nschema = client.beta.findall.extend(\n findall_id=\"findall_56ccc4d188fb41a0803a935cf485c774\",\n additional_match_limit=10,\n)\n\nprint(f\"FindAll run extended: {schema.model_dump_json(indent=2)}\")" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst schema = await client.beta.findall.extend(\n \"findall_56ccc4d188fb41a0803a935cf485c774\",\n {\n additional_match_limit: 10,\n }\n);\n\nconsole.log(`FindAll run extended: ${JSON.stringify(schema, null, 2)}`);" } ] } }, "/v1beta/findall/runs/{findall_id}/result": { "get": { "tags": [ "FindAll" ], "summary": "FindAll Run Result", "description": "Retrieve the FindAll run result at the time of the request.", "operationId": "get_findall_result_v1beta_findall_runs__findall_id__result_get", "parameters": [ { "name": "findall_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Findall Id" } }, { "name": "parallel-beta", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "deprecated": true, "title": "Parallel-Beta", "x-stainless-override-schema": { "x-stainless-param": "betas", "x-stainless-extend-default": true, "type": "array", "description": "Optional header to specify the beta version(s) to enable.", "items": { "$ref": "#/components/schemas/ParallelBeta" } } }, "deprecated": true } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindAllRunResult" }, "example": { "run": { "findall_id": "findall_56ccc4d188fb41a0803a935cf485c774", "status": { "status": "running", "is_active": true, "metrics": { "generated_candidates_count": 1, "matched_candidates_count": 1 } }, "generator": "base", "metadata": {}, "created_at": "2025-09-10T21:02:08.626446Z", "modified_at": "2025-09-10T21:02:08.627376Z" }, "candidates": [ { "candidate_id": "candidate_7594eb7c-4f4a-487f-9d0c-9d1e63ec240c", "name": "Cognition AI", "url": "cognition.ai", "match_status": "matched", "output": { "developing_ai_products_check": "yes", "raised_series_a_2024_check": "yes" }, "basis": [ { "field": "developing_ai_products_check", "citations": [ { "title": "Cognition - Devin and Cognition AI", "url": "https://cognition.ai/", "excerpts": [ "We're the makers of Devin, a collaborative AI teammate that helps ambitious engineering teams achieve more.", "An applied AI lab building the future of software engineering", "Cognition" ] } ], "reasoning": "The search results repeatedly state that Cognition AI is an 'applied AI lab building the future of software engineering' and that they developed 'Devin AI', described as the 'world's first AI software engineer'. This directly confirms they are developing AI products.", "confidence": "high" }, { "field": "raised_series_a_2024_check", "citations": [ { "title": "Cognition Labs Raises $21 Million Series A to Support AI Coding Products", "url": "https://voicebot.ai/2024/04/25/cognition-labs-raises-21-million-series-a-to-support-ai-coding-products/", "excerpts": [ "Cognition Labs Raises $21 Million Series A to Support AI Coding Products" ] } ], "reasoning": "The article from voicebot.ai, dated April 25, 2024, states that Founders Fund led a \"$21 million Series A investment\" for Cognition Labs. This confirms that Series A funding was raised in 2024.", "confidence": "low" } ] } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\nrun_result = client.beta.findall.result(\n findall_id=\"findall_56ccc4d188fb41a0803a935cf485c774\",\n)\n\nprint(f\"FindAll run {run_result.run.findall_id} result: {run_result.model_dump_json(indent=2)}\")" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst runResult = await client.beta.findall.result(\"findall_56ccc4d188fb41a0803a935cf485c774\");\n\nconsole.log(`FindAll run ${runResult.run.findall_id} result: ${JSON.stringify(runResult, null, 2)}`);" } ] } }, "/v1beta/findall/runs/{findall_id}/schema": { "get": { "tags": [ "FindAll" ], "summary": "Get FindAll Run Schema", "operationId": "get_findall_schema_v1beta_findall_runs__findall_id__schema_get", "parameters": [ { "name": "findall_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Findall Id" } }, { "name": "parallel-beta", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "deprecated": true, "title": "Parallel-Beta", "x-stainless-override-schema": { "x-stainless-param": "betas", "x-stainless-extend-default": true, "type": "array", "description": "Optional header to specify the beta version(s) to enable.", "items": { "$ref": "#/components/schemas/ParallelBeta" } } }, "deprecated": true } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindAllSchema" }, "example": { "objective": "Find all AI companies that raised Series A funding in 2024", "entity_type": "companies", "match_conditions": [ { "name": "developing_ai_products_check", "description": "Company must be developing artificial intelligence (AI) products" } ], "enrichments": [ { "processor": "core", "output_schema": { "json_schema": { "type": "object", "properties": { "ceo_name": { "type": "string", "description": "Name of the current CEO of the company. If the CEO is not publicly known, provide the name of the highest-ranking executive or founder. If no information is available, return null." } } }, "type": "json" } } ], "generator": "core", "match_limit": 50 } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\nschema = client.beta.findall.schema(\n findall_id=\"findall_56ccc4d188fb41a0803a935cf485c774\",\n)\n\nprint(f\"Schema: {schema.model_dump_json(indent=2)}\")" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst schema = await client.beta.findall.schema(\"findall_56ccc4d188fb41a0803a935cf485c774\");\n\nconsole.log(`Schema: ${JSON.stringify(schema, null, 2)}`);" } ] } }, "/v1/monitors": { "post": { "tags": [ "Monitor" ], "summary": "Create Monitor", "description": "Create a monitor.\n\nMonitors run on a fixed frequency to detect material changes in web content.\nSet `type=event_stream` to monitor a search query, or `type=snapshot` to\nmonitor a specific task run's output. The monitor runs once immediately at\ncreation, then continues on the configured schedule.", "operationId": "create_monitor_v1_monitors_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMonitorRequest" } } } }, "responses": { "201": { "description": "Monitor created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorResponse" } } } }, "401": { "description": "Unauthorized: invalid or missing credentials", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unauthorized: invalid or missing credentials" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content: request validation error", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unprocessable content: request validation error" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\nmonitor = client.monitor.create(\n type=\"event_stream\",\n frequency=\"1d\",\n settings={\"query\": \"Extract recent news about AI\"},\n)\nprint(monitor.monitor_id)" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst monitor = await client.monitor.create({\n type: 'event_stream',\n frequency: '1d',\n settings: { query: 'Extract recent news about AI' },\n});\nconsole.log(monitor.monitor_id);" } ] }, "get": { "tags": [ "Monitor" ], "summary": "List Monitors", "description": "List monitors ordered by creation time, newest first.\n\nMonitors are sorted by `created_at` descending. `limit` defaults to 100.\nUse `next_cursor` from the response and pass it as `cursor` to fetch the\nnext page. Pagination ends when `next_cursor` is absent.\n\nBy default only `active` monitors are returned. Pass `status=cancelled`\nor both values to include cancelled monitors.\n\nThe legacy Monitor API (`/v1alpha/monitors` endpoints) is documented under\nthe `Monitor (Alpha)` tag.", "operationId": "list_monitors_v1_monitors_get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pagination token from `next_cursor` in a previous response. Omit to start from the most recently created monitor.", "title": "Cursor" }, "description": "Pagination token from `next_cursor` in a previous response. Omit to start from the most recently created monitor." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 10000, "minimum": 1 }, { "type": "null" } ], "description": "Maximum number of monitors to return. Defaults to 100. Between 1 and 10000.", "title": "Limit" }, "description": "Maximum number of monitors to return. Defaults to 100. Between 1 and 10000." }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "enum": [ "event_stream", "snapshot" ], "type": "string" } }, { "type": "null" } ], "description": "Filter by monitor type. Pass multiple times to filter by multiple values. Omit to return all types.", "title": "Type" }, "description": "Filter by monitor type. Pass multiple times to filter by multiple values. Omit to return all types." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "enum": [ "active", "cancelled" ], "type": "string" } }, { "type": "null" } ], "description": "Filter by monitor status. Pass multiple times to filter by multiple values. Defaults to `active` only.", "title": "Status" }, "description": "Filter by monitor status. Pass multiple times to filter by multiple values. Defaults to `active` only." } ], "responses": { "200": { "description": "Paginated list of monitors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedMonitorResponse" } } } }, "401": { "description": "Unauthorized: invalid or missing credentials", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unauthorized: invalid or missing credentials" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\npage = client.monitor.list(limit=10)\nfor monitor in page.monitors:\n print(monitor.monitor_id, monitor.status)" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst page = await client.monitor.list({ limit: 10 });\nfor (const monitor of page.monitors) {\n console.log(monitor.monitor_id, monitor.status);\n}" } ] } }, "/v1/monitors/{monitor_id}": { "get": { "tags": [ "Monitor" ], "summary": "Retrieve Monitor", "description": "Retrieve a monitor.\n\nRetrieves a specific monitor by `monitor_id`. Returns the monitor\nconfiguration including status, frequency, query, and webhook settings.", "operationId": "retrieve_monitor_v1_monitors__monitor_id__get", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Monitor Id" } } ], "responses": { "200": { "description": "Monitor retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorResponse" } } } }, "401": { "description": "Unauthorized: invalid or missing credentials", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unauthorized: invalid or missing credentials" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Monitor not found", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Monitor not found" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\nmonitor = client.monitor.retrieve(\"monitor_id\")\nprint(monitor.status)" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst monitor = await client.monitor.retrieve('monitor_id');\nconsole.log(monitor.status);" } ] } }, "/v1/monitors/{monitor_id}/cancel": { "post": { "tags": [ "Monitor" ], "summary": "Cancel Monitor", "description": "Cancel a monitor.\n\nPermanently stops the monitor from running. Cancellation is irreversible \u2014\ncreate a new monitor to resume monitoring. Cancelling an already-cancelled\nmonitor is a no-op.", "operationId": "cancel_monitor_v1_monitors__monitor_id__cancel_post", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Monitor Id" } } ], "responses": { "200": { "description": "Monitor cancelled successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorResponse" } } } }, "401": { "description": "Unauthorized: invalid or missing credentials", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unauthorized: invalid or missing credentials" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Monitor not found", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Monitor not found" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content: request validation error", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unprocessable content: request validation error" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\nmonitor = client.monitor.cancel(\"monitor_id\")\nprint(monitor.status)" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst monitor = await client.monitor.cancel('monitor_id');\nconsole.log(monitor.status);" } ] } }, "/v1/monitors/{monitor_id}/events": { "get": { "tags": [ "Monitor" ], "summary": "List Monitor Events", "description": "List events for a monitor, newest first.\n\nPass `event_group_id` to narrow results to a single execution. Otherwise\nreturns all executions newest-first; use `next_cursor` to paginate.\nSet `include_completions=true` to also include no-change executions.", "operationId": "list_monitor_events_v1_monitors__monitor_id__events_get", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Monitor Id" } }, { "name": "event_group_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter to a single execution. Values come from `event_group_id` in webhook events and listed events. Pagination params are ignored when set.", "title": "Event Group Id" }, "description": "Filter to a single execution. Values come from `event_group_id` in webhook events and listed events. Pagination params are ignored when set." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass `next_cursor` from a previous response to retrieve more events.", "title": "Cursor" }, "description": "Pass `next_cursor` from a previous response to retrieve more events." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 100, "minimum": 1 }, { "type": "null" } ], "description": "Maximum number of events to return. Defaults to 20. Between 1 and 100.", "title": "Limit" }, "description": "Maximum number of events to return. Defaults to 20. Between 1 and 100." }, { "name": "include_completions", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, include completion events for executions that ran but detected no material changes. Useful for auditing execution history.", "default": false, "title": "Include Completions" }, "description": "When true, include completion events for executions that ran but detected no material changes. Useful for auditing execution history." } ], "responses": { "200": { "description": "Monitor events retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedMonitorEvents" } } } }, "401": { "description": "Unauthorized: invalid or missing credentials", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unauthorized: invalid or missing credentials" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Monitor not found", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Monitor not found" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content: invalid cursor or request validation error", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unprocessable content: invalid cursor or request validation error" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\npage = client.monitor.events(\"monitor_id\", limit=20)\nfor event in page.events:\n print(event)" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst page = await client.monitor.events('monitor_id', { limit: 20 });\nfor (const event of page.events) {\n console.log(event);\n}" } ] } }, "/v1/monitors/{monitor_id}/trigger": { "post": { "tags": [ "Monitor" ], "summary": "Trigger Monitor Run", "description": "Trigger an immediate monitor run.\n\nEnqueues a one-off execution of the monitor outside its normal schedule.\nThe monitor's regular schedule is not affected. An event is only emitted\nif the execution detects a material change. Cancelled monitors cannot be\ntriggered.", "operationId": "trigger_monitor_run_v1_monitors__monitor_id__trigger_post", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Monitor Id" } } ], "responses": { "204": { "description": "Monitor run enqueued." }, "401": { "description": "Unauthorized: invalid or missing credentials", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unauthorized: invalid or missing credentials" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Monitor not found", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Monitor not found" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content: request validation error", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unprocessable content: request validation error" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\nclient.monitor.trigger(\"monitor_id\")" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nawait client.monitor.trigger('monitor_id');" } ] } }, "/v1/monitors/{monitor_id}/update": { "post": { "tags": [ "Monitor" ], "summary": "Update Monitor", "description": "Update a monitor.\n\nOnly fields explicitly included in the request body are changed. Pass\n`null` for `webhook` or `metadata` to clear those fields. Pass `type` and\n`settings` to update type-specific settings on an `event_stream` monitor.\nAt least one field must be provided. Cancelled monitors cannot be updated.", "operationId": "update_monitor_v1_monitors__monitor_id__update_post", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Monitor Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMonitorRequest" } } } }, "responses": { "200": { "description": "Monitor updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorResponse" } } } }, "401": { "description": "Unauthorized: invalid or missing credentials", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unauthorized: invalid or missing credentials" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Monitor not found", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Monitor not found" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable content: request validation error", "content": { "application/json": { "example": { "type": "error", "error": { "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331", "message": "Unprocessable content: request validation error" } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-code-samples": [ { "lang": "Python", "source": "from parallel import Parallel\n\nclient = Parallel()\n\nmonitor = client.monitor.update(\n \"monitor_id\",\n frequency=\"12h\",\n type=\"event_stream\",\n settings={\"query\": \"Extract recent funding news about AI startups\"},\n)\nprint(monitor.frequency)" }, { "lang": "TypeScript", "source": "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst monitor = await client.monitor.update('monitor_id', {\n frequency: '12h',\n type: 'event_stream',\n settings: { query: 'Extract recent funding news about AI startups' },\n});\nconsole.log(monitor.frequency);" } ] } }, "/v1beta/memory/clear": { "post": { "tags": [ "Memory" ], "summary": "Clear Memory", "description": "Clears all entries from the selected memory without deleting the underlying tasks, monitors, or FindAll runs.", "operationId": "clear_memory_v1beta_memory_clear_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryClearRequest" } } }, "required": true }, "responses": { "204": { "description": "Memory cleared." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1beta/memory/evict": { "post": { "tags": [ "Memory" ], "summary": "Evict from Memory", "description": "Removes a task run, monitor, or FindAll run from the selected memory without deleting the original resource.", "operationId": "evict_memory_source_v1beta_memory_evict_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryEvictRequest" } } }, "required": true }, "responses": { "204": { "description": "Source removed from memory." }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1beta/memory/retrieve": { "post": { "tags": [ "Memory" ], "summary": "Retrieve Memory", "description": "Retrieves relevant or recent runs from the selected memory. Provide a query to rank results by relevance; leave it empty to return the most recent runs.", "operationId": "retrieve_memory_v1beta_memory_retrieve_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRetrieveRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryRetrieveResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1beta/chat/completions": { "post": { "tags": [ "Chat API (Beta)" ], "summary": "Chat Completions", "description": "Chat completions.\n\nThis endpoint can be used to get realtime chat completions. It can also be used\nwith the Task API processors to get structured, research outputs via a chat\ninterface.", "operationId": "chat_completions_v1beta_chat_completions_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } }, "required": true }, "responses": { "200": { "description": "Returns a ChatCompletion object for non-streaming requests (application/json), or a stream of ChatCompletionResponseChunk objects for streaming requests (text/event-stream) when `stream=true` is set in the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/ChatCompletionResponseChunk" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/responses": { "post": { "tags": [ "Responses API" ], "summary": "Create Response", "description": "Create a response.\n\nGenerates an answer to the given input, grounded in live web research and\nannotated with URL citations. Set `model` to `parallel`; `reasoning.effort`\n(`low`/`medium`/`high`) controls how much research is performed, trading\nresponse time for answer quality. Returns an OpenAI-format `Response` as\n`application/json`, or a `text/event-stream` of OpenAI Responses SSE\nevents when `stream=true`.", "operationId": "create_response_v1_responses_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "Returns a Response object for non-streaming requests (application/json), or a stream of OpenAI Responses streaming events (text/event-stream) when `stream=true` is set in the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Response" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/ResponseStreamEvent" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "AdvancedExtractSettings": { "properties": { "fetch_policy": { "anyOf": [ { "$ref": "#/components/schemas/FetchPolicy" }, { "type": "null" } ], "description": "Fetch policy: determines when to return cached content from the index (faster) vs fetching live content (fresher). Default is to use a dynamic policy based on the search objective and url. Note: enabling live fetch significantly increases extract latency because it requires fetching content from source websites." }, "excerpt_settings": { "anyOf": [ { "$ref": "#/components/schemas/V1ExcerptSettings" }, { "type": "null" } ], "description": "Controls excerpt sizes. Provide excerpt settings for fine-grained control, or omit to use defaults." }, "full_content": { "anyOf": [ { "$ref": "#/components/schemas/FullContentSettings" }, { "type": "boolean" } ], "title": "Full Content", "description": "Controls full content extraction. Set to true to enable with defaults, false to disable, or provide FullContentSettings for fine-grained control.", "default": false } }, "additionalProperties": false, "type": "object", "title": "AdvancedExtractSettings", "description": "Advanced extract configuration.\n\nThese settings may impact result quality and latency unless used carefully.\nSee https://docs.parallel.ai/search/advanced-extract-settings for more info." }, "AdvancedMonitorSettings": { "properties": { "source_policy": { "anyOf": [ { "$ref": "#/components/schemas/SourcePolicy" }, { "type": "null" } ], "description": "Domain filtering preferences: preferred and disallowed domains for monitor search results.", "examples": [ { "exclude_domains": [ "reddit.com", "x.com", ".ai" ], "include_domains": [ "wikipedia.org", "usa.gov", ".edu" ] } ] }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location", "description": "ISO 3166-1 alpha-2 country code for geo-targeted monitor results.", "examples": [ "us", "gb", "de", "jp" ] } }, "type": "object", "title": "AdvancedMonitorSettings", "description": "Advanced monitor configuration." }, "AdvancedSearchSettings": { "properties": { "source_policy": { "anyOf": [ { "$ref": "#/components/schemas/SourcePolicy" }, { "type": "null" } ], "description": "Domain and date filtering preferences for search results." }, "fetch_policy": { "anyOf": [ { "$ref": "#/components/schemas/FetchPolicy" }, { "type": "null" } ], "description": "Fetch policy: determines when to return cached content from the index (faster) vs fetching live content (fresher). Default is to disable live fetch and return cached content from the index. Note: enabling live fetch significantly increases search latency because it requires fetching content from source websites." }, "excerpt_settings": { "anyOf": [ { "$ref": "#/components/schemas/V1ExcerptSettings" }, { "type": "null" } ], "description": "Controls excerpt sizes. Provide excerpt settings for fine-grained control, or omit to use defaults." }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location", "description": "ISO 3166-1 alpha-2 country code for geo-targeted search results.", "examples": [ "us", "gb", "de", "jp" ] }, "max_results": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Results", "description": "Upper bound on the number of results to return. Defaults to 10 if not provided." } }, "additionalProperties": false, "type": "object", "title": "AdvancedSearchSettings", "description": "Advanced search configuration.\n\nThese settings may impact result quality and latency unless used carefully.\nSee https://docs.parallel.ai/search/advanced-search-settings for more info." }, "AutoSchema": { "properties": { "type": { "type": "string", "const": "auto", "title": "Type", "description": "The type of schema being defined. Always `auto`.", "default": "auto" } }, "type": "object", "title": "AutoSchema", "description": "Auto schema for a task input or output." }, "ChatCompletion": { "properties": { "id": { "type": "string", "title": "Id", "description": "The id of the chat completion." }, "choices": { "items": { "$ref": "#/components/schemas/Choice" }, "type": "array", "title": "Choices" }, "created": { "type": "integer", "title": "Created" }, "model": { "type": "string", "title": "Model" }, "object": { "type": "string", "const": "chat.completion", "title": "Object" }, "moderation": { "anyOf": [ { "$ref": "#/components/schemas/openai__types__chat__chat_completion__Moderation" }, { "type": "null" } ] }, "service_tier": { "anyOf": [ { "type": "string", "enum": [ "auto", "default", "flex", "scale", "priority" ] }, { "type": "null" } ], "title": "Service Tier" }, "system_fingerprint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "System Fingerprint" }, "usage": { "anyOf": [ { "$ref": "#/components/schemas/CompletionUsage" }, { "type": "null" } ] }, "basis": { "items": { "$ref": "#/components/schemas/FieldBasis" }, "type": "array", "title": "Basis", "description": "Basis for the chat completion, including citations and reasoning supporting the output.", "default": [] }, "interaction_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Interaction Id", "description": "Identifier for this interaction. Pass as previous_interaction_id for follow-ups." } }, "additionalProperties": true, "type": "object", "required": [ "id", "choices", "created", "model", "object" ], "title": "ChatCompletion", "description": "Chat completion response." }, "ChatCompletionRequest": { "properties": { "model": { "type": "string", "title": "Model", "description": "The model to use for chat completions." }, "messages": { "items": { "$ref": "#/components/schemas/ChatMessage" }, "type": "array", "title": "Messages", "description": "The messages to use for chat completions." }, "stream": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Stream", "description": "Whether to stream the chat completions." }, "response_format": { "anyOf": [ { "$ref": "#/components/schemas/openai__types__shared_params__response_format_text__ResponseFormatText" }, { "$ref": "#/components/schemas/ResponseFormatJSONSchema" }, { "$ref": "#/components/schemas/openai__types__shared_params__response_format_json_object__ResponseFormatJSONObject" }, { "type": "null" } ], "title": "Response Format", "description": "The response format to use for chat completions. OpenAI compatible." }, "max_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Tokens", "description": "The maximum number of tokens to generate. Unsupported." }, "temperature": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Temperature", "description": "The temperature to use for chat completions. Unsupported." }, "top_p": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Top P", "description": "The top p to use for chat completions. Unsupported." }, "n": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "N", "description": "The number of chat completions to generate. Unsupported." }, "presence_penalty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Presence Penalty", "description": "The presence penalty to use for chat completions. Unsupported." }, "frequency_penalty": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Frequency Penalty", "description": "The frequency penalty to use for chat completions. Unsupported." }, "previous_interaction_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Interaction Id", "description": "Interaction ID from a previous chat completion to use as context." } }, "type": "object", "required": [ "model", "messages" ], "title": "ChatCompletionRequest", "description": "Request for the chat completions endpoint.\n\nNote that all parameters except for `model`, `stream`, and `response_format`\nare ignored." }, "ChatCompletionTokenLogprob": { "additionalProperties": true, "properties": { "token": { "title": "Token", "type": "string" }, "bytes": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Bytes" }, "logprob": { "title": "Logprob", "type": "number" }, "top_logprobs": { "items": { "$ref": "#/components/schemas/TopLogprob" }, "title": "Top Logprobs", "type": "array" } }, "required": [ "token", "logprob", "top_logprobs" ], "title": "ChatCompletionTokenLogprob", "type": "object" }, "ChatMessage": { "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant" ], "title": "Role", "description": "The role of the chat message." }, "content": { "type": "string", "title": "Content", "description": "The content of the chat message." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "An optional name for the participant. Provides the model information to differentiate between participants of the same role." } }, "type": "object", "required": [ "role", "content" ], "title": "ChatMessage", "description": "Chat message for OpenAI API." }, "Choice": { "additionalProperties": true, "properties": { "delta": { "$ref": "#/components/schemas/ChoiceDelta" }, "finish_reason": { "anyOf": [ { "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Finish Reason" }, "index": { "title": "Index", "type": "integer" }, "logprobs": { "anyOf": [ { "$ref": "#/components/schemas/ChoiceLogprobs" }, { "type": "null" } ], "default": null } }, "required": [ "delta", "index" ], "title": "Choice", "type": "object" }, "ChoiceLogprobs": { "additionalProperties": true, "description": "Log probability information for the choice.", "properties": { "content": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ChatCompletionTokenLogprob" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Content" }, "refusal": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ChatCompletionTokenLogprob" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Refusal" } }, "title": "ChoiceLogprobs", "type": "object" }, "Citation": { "description": "A citation for a task output.", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Title of the citation.", "title": "Title" }, "url": { "description": "URL of the citation.", "title": "Url", "type": "string" }, "excerpts": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Excerpts from the citation supporting the output. Only certain processors provide excerpts.", "title": "Excerpts" } }, "required": [ "url" ], "title": "Citation", "type": "object" }, "CompletionTokensDetails": { "additionalProperties": true, "description": "Breakdown of tokens used in a completion.", "properties": { "accepted_prediction_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Accepted Prediction Tokens" }, "audio_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Audio Tokens" }, "reasoning_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Reasoning Tokens" }, "rejected_prediction_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Rejected Prediction Tokens" } }, "title": "CompletionTokensDetails", "type": "object" }, "CompletionUsage": { "additionalProperties": true, "description": "Usage statistics for the completion request.", "properties": { "completion_tokens": { "title": "Completion Tokens", "type": "integer" }, "prompt_tokens": { "title": "Prompt Tokens", "type": "integer" }, "total_tokens": { "title": "Total Tokens", "type": "integer" }, "completion_tokens_details": { "anyOf": [ { "$ref": "#/components/schemas/CompletionTokensDetails" }, { "type": "null" } ], "default": null }, "prompt_tokens_details": { "anyOf": [ { "$ref": "#/components/schemas/PromptTokensDetails" }, { "type": "null" } ], "default": null } }, "required": [ "completion_tokens", "prompt_tokens", "total_tokens" ], "title": "CompletionUsage", "type": "object" }, "CreateMonitorRequest": { "properties": { "type": { "type": "string", "enum": [ "event_stream", "snapshot" ], "title": "Type", "description": "Type of monitor to create. `event_stream` monitors a search query for material changes; `snapshot` monitors a specific task run's output. Determines the expected shape of `settings`.", "examples": [ "event_stream", "snapshot" ] }, "frequency": { "type": "string", "title": "Frequency", "description": "Frequency of the monitor. Format: '' where unit is 'h' (hours), 'd' (days), or 'w' (weeks). Must be between 1h and 30d (inclusive).", "examples": [ "1h", "12h", "1d", "7d", "30d" ] }, "processor": { "type": "string", "enum": [ "lite", "base" ], "title": "Processor", "description": "Processor to use for the monitor. `lite` is faster and cheaper; `base` performs more thorough analysis at higher cost and latency. Defaults to `lite`.", "default": "lite" }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/MonitorWebhook" }, { "type": "null" } ], "description": "Webhook to receive notifications about the monitor's execution." }, "metadata": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "User-provided metadata stored with the monitor and echoed back in webhook notifications and GET responses, so you can map events to objects in your application. Keys: max 16 chars; values: max 512 chars.", "examples": [ { "slack_thread_id": "1234567890.123456", "user_id": "U123ABC" } ] }, "memory_scope_key": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, { "type": "null" } ], "title": "Memory Scope Key", "description": "User-provided key identifying the memory scope to use. Omit to use personal memory, if available." }, "settings": { "anyOf": [ { "$ref": "#/components/schemas/MonitorEventStreamSettings" }, { "$ref": "#/components/schemas/MonitorSnapshotSettings" } ], "title": "Settings", "description": "Type-specific settings for the monitor. The expected shape is determined by the root `type` field: pass `MonitorEventStreamSettings` when `type` is `event_stream`, and `MonitorSnapshotSettings` when `type` is `snapshot`." } }, "type": "object", "required": [ "type", "frequency", "settings" ], "title": "CreateMonitorRequest", "description": "Request body to create a monitor.\n\nThe `type` field at the root determines the expected shape of `settings`:\n`event_stream` requires `MonitorEventStreamSettings`, and `snapshot`\nrequires `MonitorSnapshotSettings`." }, "CreateTaskGroupRequest": { "properties": { "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "User-provided metadata stored with the task group." } }, "type": "object", "title": "CreateTaskGroupRequest", "description": "Request to create a task group." }, "EntityItem": { "properties": { "name": { "type": "string", "title": "Name", "description": "Entity name." }, "url": { "type": "string", "title": "Url", "description": "Canonical URL for the entity." }, "description": { "type": "string", "title": "Description", "description": "Descriptive text about the entity." } }, "type": "object", "required": [ "name", "url", "description" ], "title": "EntityItem" }, "Error": { "properties": { "ref_id": { "type": "string", "title": "Reference ID", "description": "Reference ID for the error." }, "message": { "type": "string", "title": "Message", "description": "Human-readable message." }, "detail": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Detail", "description": "Optional detail supporting the error." } }, "type": "object", "required": [ "ref_id", "message" ], "title": "Error", "description": "An error message." }, "ErrorEvent": { "properties": { "type": { "type": "string", "const": "error", "title": "Type", "description": "Event type; always 'error'." }, "error": { "$ref": "#/components/schemas/Error", "description": "Error." } }, "type": "object", "required": [ "type", "error" ], "title": "ErrorEvent", "description": "Event indicating an error." }, "ErrorResponse": { "properties": { "type": { "type": "string", "const": "error", "title": "Type", "description": "Always 'error'." }, "error": { "$ref": "#/components/schemas/Error", "description": "Error." } }, "type": "object", "required": [ "type", "error" ], "title": "ErrorResponse", "description": "Response object used for non-200 status codes." }, "ExcludeCandidate": { "properties": { "name": { "type": "string", "title": "Name", "description": "Name of the entity to exclude from results." }, "url": { "type": "string", "title": "Url", "description": "URL of the entity to exclude from results." } }, "type": "object", "required": [ "name", "url" ], "title": "ExcludeCandidate", "description": "Exclude candidate input model for FindAll run." }, "ExtractError": { "properties": { "url": { "type": "string", "title": "Url" }, "error_type": { "type": "string", "title": "Error Type", "description": "Error type." }, "http_status_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Http Status Code", "description": "HTTP status code, if available." }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content", "description": "Content returned for http client or server errors, if any." } }, "type": "object", "required": [ "url", "error_type", "http_status_code", "content" ], "title": "ExtractError", "description": "Extract error details." }, "FetchPolicy": { "properties": { "max_age_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Age Seconds", "description": "Maximum age of cached content in seconds to trigger a live fetch. Minimum value 600 seconds (10 minutes).", "examples": [ 86400 ] }, "timeout_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Timeout Seconds", "description": "Timeout in seconds for fetching live content if unavailable in cache.", "examples": [ 60.0 ] }, "disable_cache_fallback": { "type": "boolean", "title": "Disable Cache Fallback", "description": "If false, fallback to cached content older than max-age if live fetch fails or times out. If true, returns an error instead.", "default": false } }, "type": "object", "title": "FetchPolicy", "description": "Policy for live fetching web results." }, "FieldBasis": { "description": "Citations and reasoning supporting one field of a task output.", "properties": { "field": { "description": "Name of the output field.", "title": "Field", "type": "string" }, "citations": { "default": [], "description": "List of citations supporting the output field.", "items": { "$ref": "#/components/schemas/Citation" }, "title": "Citations", "type": "array" }, "reasoning": { "description": "Reasoning for the output field.", "title": "Reasoning", "type": "string" }, "confidence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Confidence level for the output field. Only certain processors provide confidence levels.", "examples": [ "low", "medium", "high" ], "title": "Confidence" } }, "required": [ "field", "reasoning" ], "title": "FieldBasis", "type": "object" }, "FindAllCandidate": { "properties": { "candidate_id": { "type": "string", "title": "Candidate ID", "description": "ID of the candidate." }, "name": { "type": "string", "title": "Name", "description": "Name of the candidate." }, "url": { "type": "string", "title": "Url", "description": "URL that provides context or details of the entity for disambiguation." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Brief description of the entity that can help answer whether entity satisfies the query." }, "match_status": { "type": "string", "enum": [ "generated", "matched", "unmatched", "discarded" ], "title": "Match Status", "description": "Status of the candidate. One of generated, matched, unmatched, discarded." }, "output": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output", "description": "Results of the match condition evaluations for this candidate. This object contains the structured output that determines whether the candidate matches the overall FindAll objective." }, "basis": { "anyOf": [ { "items": { "$ref": "#/components/schemas/FieldBasis" }, "type": "array" }, { "type": "null" } ], "title": "Basis", "description": "List of FieldBasis objects supporting the output." } }, "type": "object", "required": [ "candidate_id", "name", "url", "match_status" ], "title": "FindAllCandidate", "description": "Candidate for a find all run that may end up as a match.\n\nContains all the candidate's metadata and the output of the match conditions.\nA candidate is a match if all match conditions are satisfied." }, "FindAllCandidateMatchStatusEvent": { "properties": { "type": { "type": "string", "enum": [ "findall.candidate.generated", "findall.candidate.matched", "findall.candidate.unmatched", "findall.candidate.discarded", "findall.candidate.enriched" ], "title": "Type", "description": "Event type; one of findall.candidate.generated, findall.candidate.matched, findall.candidate.unmatched, findall.candidate.discarded, findall.candidate.enriched." }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Timestamp of the event." }, "event_id": { "type": "string", "title": "Event Id", "description": "Unique event identifier for the event." }, "data": { "$ref": "#/components/schemas/FindAllCandidate", "description": "The candidate whose match status has been updated." } }, "type": "object", "required": [ "type", "timestamp", "event_id", "data" ], "title": "FindAllCandidateMatchStatusEvent", "description": "Event containing a candidate whose match status has changed." }, "FindAllCandidateMetrics": { "properties": { "generated_candidates_count": { "type": "integer", "title": "Generated Candidates Count", "description": "Number of candidates that were selected.", "default": 0 }, "matched_candidates_count": { "type": "integer", "title": "Matched Candidates Count", "description": "Number of candidates that evaluated to matched.", "default": 0 } }, "type": "object", "title": "FindAllCandidateMetrics", "description": "Metrics object for FindAll run." }, "FindAllEnrichInput": { "properties": { "processor": { "type": "string", "title": "Processor", "description": "Processor to use for the task.", "default": "core" }, "output_schema": { "$ref": "#/components/schemas/JsonSchema", "description": "JSON schema for the enrichment output schema for the FindAll run." }, "mcp_servers": { "anyOf": [ { "items": { "$ref": "#/components/schemas/McpServer" }, "type": "array" }, { "type": "null" } ], "title": "Mcp Servers", "description": "List of MCP servers to use for the task." } }, "type": "object", "required": [ "output_schema" ], "title": "FindAllEnrichInput", "description": "Input model for FindAll enrich." }, "FindAllEntitySearchRequest": { "properties": { "entity_type": { "type": "string", "enum": [ "people", "companies" ], "title": "Entity Type", "description": "Type of entity to search for." }, "objective": { "type": "string", "title": "Objective", "description": "Natural language description of target entities." }, "match_limit": { "type": "integer", "maximum": 1000.0, "minimum": 5.0, "title": "Match Limit", "description": "Maximum number of entities to return. Must be between 5 and 1000 (inclusive). May return fewer results. Defaults to 100.", "default": 100 } }, "type": "object", "required": [ "entity_type", "objective" ], "title": "FindAllEntitySearchRequest" }, "FindAllEntitySearchResponse": { "properties": { "entity_set_id": { "type": "string", "title": "Entity Set Id", "description": "Entity set request ID. Example: `entity_set_cad0a6d2dec046bd95ae900527d880e7`" }, "entities": { "items": { "$ref": "#/components/schemas/EntityItem" }, "type": "array", "title": "Entities", "description": "Ranked list of entities." } }, "type": "object", "required": [ "entity_set_id", "entities" ], "title": "FindAllEntitySearchResponse" }, "FindAllExtendInput": { "properties": { "additional_match_limit": { "type": "integer", "title": "Additional Match Limit", "description": "Additional number of matches to find for this FindAll run. This value will be added to the current match limit to determine the new total match limit. Must be greater than 0." } }, "type": "object", "required": [ "additional_match_limit" ], "title": "FindAllExtendInput", "description": "Input model for FindAll extend." }, "FindAllMemoryResult": { "properties": { "kind": { "type": "string", "const": "findall", "title": "Kind", "default": "findall" }, "id": { "type": "string", "title": "Id", "description": "ID of the FindAll run." }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "When the FindAll result was last updated, as an RFC 3339 timestamp." }, "input_excerpt": { "type": "string", "title": "Input Excerpt", "description": "Preview of the run's objective. May be truncated." }, "matched_count": { "type": "integer", "title": "Matched Count", "description": "Current number of matched entities." } }, "type": "object", "required": [ "id", "updated_at", "input_excerpt", "matched_count" ], "title": "FindAllMemoryResult" }, "FindAllRun": { "properties": { "findall_id": { "type": "string", "title": "FindAll ID", "description": "ID of the FindAll run." }, "status": { "$ref": "#/components/schemas/FindAllRunStatus", "description": "Status object for the FindAll run." }, "generator": { "type": "string", "enum": [ "base", "core", "pro", "preview" ], "title": "Generator", "description": "Generator for the FindAll run." }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Metadata for the FindAll run." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At", "description": "Timestamp of the creation of the run, in RFC 3339 format." }, "modified_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Modified At", "description": "Timestamp of the latest modification to the FindAll run result, in RFC 3339 format." } }, "type": "object", "required": [ "findall_id", "status", "generator" ], "title": "FindAllRun", "description": "FindAll run object with status and metadata." }, "FindAllRunInput": { "properties": { "objective": { "type": "string", "title": "Objective", "description": "Natural language objective of the FindAll run." }, "entity_type": { "type": "string", "title": "Entity Type", "description": "Type of the entity for the FindAll run." }, "match_conditions": { "items": { "$ref": "#/components/schemas/MatchCondition" }, "type": "array", "title": "Match Conditions", "description": "List of match conditions for the FindAll run." }, "generator": { "type": "string", "enum": [ "base", "core", "pro", "preview" ], "title": "Generator", "description": "Generator for the FindAll run. One of base, core, pro, preview." }, "match_limit": { "type": "integer", "title": "Match Limit", "description": "Maximum number of matches to find for this FindAll run. Must be between 5 and 1000 (inclusive). May return fewer results." }, "exclude_list": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ExcludeCandidate" }, "type": "array", "maxItems": 10000 }, { "type": "null" } ], "title": "Exclude List", "description": "List of entity names/IDs to exclude from results. At most 10,000 entries are allowed." }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Metadata for the FindAll run." }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "null" } ], "description": "Webhook for the FindAll run." }, "memory_scope_key": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, { "type": "null" } ], "title": "Memory Scope Key", "description": "User-provided key identifying the memory scope to use. Omit to use personal memory, if available." } }, "type": "object", "required": [ "objective", "entity_type", "match_conditions", "generator", "match_limit" ], "title": "FindAllRunInput", "description": "Input model for FindAll run." }, "FindAllRunResult": { "properties": { "run": { "$ref": "#/components/schemas/FindAllRun", "description": "FindAll run object." }, "candidates": { "items": { "$ref": "#/components/schemas/FindAllCandidate" }, "type": "array", "title": "Candidates", "description": "All evaluated candidates at the time of the snapshot." }, "last_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Event Id", "description": "ID of the last event of the run at the time of the request. This can be used to resume streaming from the last event." } }, "type": "object", "required": [ "run", "candidates" ], "title": "FindAllRunResult", "description": "Complete FindAll search results.\n\nRepresents a snapshot of a FindAll run, including run metadata and a list of\ncandidate entities with their match status and details at the time the snapshot was\ntaken." }, "FindAllRunStatus": { "properties": { "status": { "type": "string", "enum": [ "queued", "action_required", "running", "completed", "failed", "cancelling", "cancelled" ], "title": "Status", "description": "Status of the FindAll run." }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether the FindAll run is active" }, "metrics": { "$ref": "#/components/schemas/FindAllCandidateMetrics", "description": "Candidate metrics for the FindAll run." }, "termination_reason": { "anyOf": [ { "type": "string", "enum": [ "low_match_rate", "match_limit_met", "candidates_exhausted", "user_cancelled", "error_occurred", "timeout", "insufficient_funds" ] }, { "type": "null" } ], "title": "Termination Reason", "description": "Reason for termination when FindAll run is in terminal status." } }, "type": "object", "required": [ "status", "is_active", "metrics" ], "title": "FindAllRunStatus", "description": "Status object for FindAll run." }, "FindAllRunStatusEvent": { "properties": { "type": { "type": "string", "enum": [ "findall.status" ], "const": "findall.status", "title": "Type", "description": "Event type; always 'findall.status'." }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Timestamp of the event." }, "event_id": { "type": "string", "title": "Event Id", "description": "Unique event identifier for the event." }, "data": { "$ref": "#/components/schemas/FindAllRun", "description": "Updated FindAll run information." } }, "type": "object", "required": [ "type", "timestamp", "event_id", "data" ], "title": "FindAllRunStatusEvent", "description": "Event containing status update for FindAll run." }, "FindAllSchema": { "properties": { "objective": { "type": "string", "title": "Objective", "description": "Natural language objective of the FindAll run.", "examples": [ "Find all AI companies that raised Series A funding in 2024" ] }, "entity_type": { "type": "string", "title": "Entity Type", "description": "Type of the entity for the FindAll run." }, "match_conditions": { "items": { "$ref": "#/components/schemas/MatchCondition" }, "type": "array", "title": "Match Conditions", "description": "List of match conditions for the FindAll run." }, "enrichments": { "anyOf": [ { "items": { "$ref": "#/components/schemas/FindAllEnrichInput" }, "type": "array" }, { "type": "null" } ], "title": "Enrichments", "description": "List of enrichment inputs for the FindAll run." }, "generator": { "type": "string", "enum": [ "base", "core", "pro", "preview" ], "title": "Generator", "description": "The generator of the FindAll run.", "default": "core" }, "match_limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Match Limit", "description": "Max number of candidates to evaluate" } }, "type": "object", "required": [ "objective", "entity_type", "match_conditions" ], "title": "FindAllSchema", "description": "Response model for FindAll ingest." }, "FindAllSchemaUpdatedEvent": { "properties": { "type": { "type": "string", "enum": [ "findall.schema.updated" ], "const": "findall.schema.updated", "title": "Type", "description": "Event type; always 'findall.schema.updated'." }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Timestamp of the event." }, "event_id": { "type": "string", "title": "Event Id", "description": "Unique event identifier for the event." }, "data": { "$ref": "#/components/schemas/FindAllSchema", "description": "Updated FindAll schema." } }, "type": "object", "required": [ "type", "timestamp", "event_id", "data" ], "title": "FindAllSchemaUpdatedEvent", "description": "Event containing full snapshot of FindAll run state." }, "FullContentSettings": { "properties": { "max_chars_per_result": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Chars Per Result", "description": "Optional limit on the number of characters to include in the full content for each url. Full content always starts at the beginning of the page and is truncated at the limit if necessary." } }, "type": "object", "title": "FullContentSettings", "description": "Optional settings for returning full content." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "IncompleteDetails": { "additionalProperties": true, "description": "Details about why the response is incomplete.", "properties": { "reason": { "anyOf": [ { "enum": [ "max_output_tokens", "content_filter" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Reason" } }, "title": "IncompleteDetails", "type": "object" }, "IngestInput": { "properties": { "objective": { "type": "string", "title": "Objective", "description": "Natural language objective to create a FindAll run spec.", "examples": [ "Find all AI companies that raised Series A funding in 2024" ] } }, "type": "object", "required": [ "objective" ], "title": "IngestInput", "description": "Input model for FindAll ingest." }, "InputTokensDetails": { "additionalProperties": true, "description": "A detailed breakdown of the input tokens.", "properties": { "cached_tokens": { "title": "Cached Tokens", "type": "integer" } }, "required": [ "cached_tokens" ], "title": "InputTokensDetails", "type": "object" }, "JSONSchema": { "properties": { "name": { "type": "string", "title": "Name" }, "description": { "type": "string", "title": "Description" }, "schema": { "additionalProperties": false, "type": "object", "title": "Schema" }, "strict": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Strict" } }, "type": "object", "required": [ "name" ], "title": "JSONSchema", "description": "Structured Outputs configuration options, including a JSON Schema." }, "JsonSchema": { "properties": { "json_schema": { "additionalProperties": true, "type": "object", "title": "Json Schema", "description": "A JSON Schema object. Only a subset of JSON Schema is supported.", "examples": [ { "additionalProperties": false, "properties": { "gdp": { "description": "GDP in USD for the year, formatted like '$3.1 trillion (2023)'", "type": "string" } }, "required": [ "gdp" ], "type": "object" } ] }, "type": { "type": "string", "const": "json", "title": "Type", "description": "The type of schema being defined. Always `json`.", "default": "json" } }, "type": "object", "required": [ "json_schema" ], "title": "JsonSchema", "description": "JSON schema for a task input or output." }, "MatchCondition": { "properties": { "name": { "type": "string", "title": "Name", "description": "Name of the match condition." }, "description": { "type": "string", "title": "Description", "description": "Detailed description of the match condition. Include as much specific information as possible to help improve the quality and accuracy of Find All run results.", "examples": [ "Company must have SOC2 Type II certification (not Type I). Look for evidence in: trust centers, security/compliance pages, audit reports, or press releases specifically mentioning 'SOC2 Type II'. If no explicit SOC2 Type II mention is found, consider requirement not satisfied." ] } }, "type": "object", "required": [ "name", "description" ], "title": "MatchCondition", "description": "Match condition model for FindAll ingest." }, "McpServer": { "properties": { "type": { "type": "string", "const": "url", "title": "Type", "description": "Type of MCP server being configured. Always `url`.", "default": "url" }, "url": { "type": "string", "title": "Url", "description": "URL of the MCP server." }, "headers": { "anyOf": [ { "additionalProperties": { "type": "string", "format": "password", "writeOnly": true }, "type": "object" }, { "type": "null" } ], "title": "Headers", "description": "Headers for the MCP server." }, "name": { "type": "string", "title": "Name", "description": "Name of the MCP server." }, "allowed_tools": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Tools", "description": "List of allowed tools for the MCP server." } }, "type": "object", "required": [ "url", "name" ], "title": "McpServer", "description": "MCP server configuration." }, "McpToolCall": { "properties": { "tool_call_id": { "type": "string", "title": "Tool Call ID", "description": "Identifier for the tool call." }, "server_name": { "type": "string", "title": "Server Name", "description": "Name of the MCP server." }, "tool_name": { "type": "string", "title": "Tool Name", "description": "Name of the tool being called." }, "arguments": { "type": "string", "title": "Arguments", "description": "Arguments used to call the MCP tool." }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Content", "description": "Output received from the tool call, if successful." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message if the tool call failed." } }, "type": "object", "required": [ "tool_call_id", "server_name", "tool_name", "arguments" ], "title": "McpToolCall", "description": "Result of an MCP tool call." }, "MemoryClearRequest": { "properties": { "memory_scope_key": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, { "type": "null" } ], "title": "Memory Scope Key", "description": "User-provided key identifying the memory scope to use. Omit to use personal memory, if available." } }, "type": "object", "title": "MemoryClearRequest" }, "MemoryEvictRequest": { "properties": { "memory_scope_key": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, { "type": "null" } ], "title": "Memory Scope Key", "description": "User-provided key identifying the memory scope to use. Omit to use personal memory, if available." }, "kind": { "type": "string", "enum": [ "task", "monitor", "findall" ], "title": "Kind", "description": "Kind of source to evict: `task`, `monitor`, or `findall`." }, "id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$", "title": "Id", "description": "ID of the task run, monitor, or FindAll run to evict." } }, "type": "object", "required": [ "kind", "id" ], "title": "MemoryEvictRequest" }, "MemoryRetrieveRequest": { "properties": { "query": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "title": "Query", "description": "Concise query describing the memories to retrieve. Empty queries return the most recent memories." }, "limit": { "type": "integer", "maximum": 25.0, "minimum": 1.0, "title": "Limit", "description": "Maximum number of memories to return.", "default": 10 }, "kind": { "anyOf": [ { "type": "string", "enum": [ "task", "monitor", "findall" ] }, { "type": "null" } ], "title": "Kind", "description": "Filter memories by kind: `task`, `monitor`, or `findall`." }, "since": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date-time", "title": "Since", "description": "Only return memories sourced from task, monitor, or FindAll runs completed at or after this RFC 3339 timestamp.", "examples": [ "2026-07-15T17:30:00Z" ] }, "memory_scope_key": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, { "type": "null" } ], "title": "Memory Scope Key", "description": "User-provided key identifying the memory scope to use. Omit to use personal memory, if available." } }, "type": "object", "title": "MemoryRetrieveRequest" }, "MemoryRetrieveResponse": { "properties": { "results": { "items": { "oneOf": [ { "$ref": "#/components/schemas/TaskMemoryResult" }, { "$ref": "#/components/schemas/MonitorMemoryResult" }, { "$ref": "#/components/schemas/FindAllMemoryResult" } ], "discriminator": { "propertyName": "kind", "mapping": { "findall": "#/components/schemas/FindAllMemoryResult", "monitor": "#/components/schemas/MonitorMemoryResult", "task": "#/components/schemas/TaskMemoryResult" } } }, "type": "array", "title": "Results" } }, "type": "object", "required": [ "results" ], "title": "MemoryRetrieveResponse" }, "ModerationInputModerationResult": { "additionalProperties": true, "description": "A moderation result produced for the response input or output.", "properties": { "categories": { "additionalProperties": { "type": "boolean" }, "title": "Categories", "type": "object" }, "category_applied_input_types": { "additionalProperties": { "items": { "enum": [ "text", "image" ], "type": "string" }, "type": "array" }, "title": "Category Applied Input Types", "type": "object" }, "category_scores": { "additionalProperties": { "type": "number" }, "title": "Category Scores", "type": "object" }, "flagged": { "title": "Flagged", "type": "boolean" }, "model": { "title": "Model", "type": "string" }, "type": { "const": "moderation_result", "title": "Type", "type": "string" } }, "required": [ "categories", "category_applied_input_types", "category_scores", "flagged", "model", "type" ], "title": "ModerationInputModerationResult", "type": "object" }, "ModerationInputModerationResults": { "additionalProperties": true, "description": "Successful moderation results for the request input or generated output.", "properties": { "model": { "title": "Model", "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/ModerationInputModerationResultsResult" }, "title": "Results", "type": "array" }, "type": { "const": "moderation_results", "title": "Type", "type": "string" } }, "required": [ "model", "results", "type" ], "title": "ModerationInputModerationResults", "type": "object" }, "ModerationInputModerationResultsResult": { "additionalProperties": true, "description": "A moderation result produced for the response input or output.", "properties": { "categories": { "additionalProperties": { "type": "boolean" }, "title": "Categories", "type": "object" }, "category_applied_input_types": { "additionalProperties": { "items": { "enum": [ "text", "image" ], "type": "string" }, "type": "array" }, "title": "Category Applied Input Types", "type": "object" }, "category_scores": { "additionalProperties": { "type": "number" }, "title": "Category Scores", "type": "object" }, "flagged": { "title": "Flagged", "type": "boolean" }, "model": { "title": "Model", "type": "string" }, "type": { "const": "moderation_result", "title": "Type", "type": "string" } }, "required": [ "categories", "category_applied_input_types", "category_scores", "flagged", "model", "type" ], "title": "ModerationInputModerationResultsResult", "type": "object" }, "ModerationOutputModerationResult": { "additionalProperties": true, "description": "A moderation result produced for the response input or output.", "properties": { "categories": { "additionalProperties": { "type": "boolean" }, "title": "Categories", "type": "object" }, "category_applied_input_types": { "additionalProperties": { "items": { "enum": [ "text", "image" ], "type": "string" }, "type": "array" }, "title": "Category Applied Input Types", "type": "object" }, "category_scores": { "additionalProperties": { "type": "number" }, "title": "Category Scores", "type": "object" }, "flagged": { "title": "Flagged", "type": "boolean" }, "model": { "title": "Model", "type": "string" }, "type": { "const": "moderation_result", "title": "Type", "type": "string" } }, "required": [ "categories", "category_applied_input_types", "category_scores", "flagged", "model", "type" ], "title": "ModerationOutputModerationResult", "type": "object" }, "ModerationOutputModerationResults": { "additionalProperties": true, "description": "Successful moderation results for the request input or generated output.", "properties": { "model": { "title": "Model", "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/ModerationOutputModerationResultsResult" }, "title": "Results", "type": "array" }, "type": { "const": "moderation_results", "title": "Type", "type": "string" } }, "required": [ "model", "results", "type" ], "title": "ModerationOutputModerationResults", "type": "object" }, "ModerationOutputModerationResultsResult": { "additionalProperties": true, "description": "A moderation result produced for the response input or output.", "properties": { "categories": { "additionalProperties": { "type": "boolean" }, "title": "Categories", "type": "object" }, "category_applied_input_types": { "additionalProperties": { "items": { "enum": [ "text", "image" ], "type": "string" }, "type": "array" }, "title": "Category Applied Input Types", "type": "object" }, "category_scores": { "additionalProperties": { "type": "number" }, "title": "Category Scores", "type": "object" }, "flagged": { "title": "Flagged", "type": "boolean" }, "model": { "title": "Model", "type": "string" }, "type": { "const": "moderation_result", "title": "Type", "type": "string" } }, "required": [ "categories", "category_applied_input_types", "category_scores", "flagged", "model", "type" ], "title": "ModerationOutputModerationResultsResult", "type": "object" }, "MonitorCompletionEvent": { "properties": { "event_type": { "type": "string", "enum": [ "completion" ], "const": "completion", "title": "Event Type", "description": "Discriminant for the completion event variant.", "default": "completion" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Timestamp of when the monitor execution completed, as an RFC 3339 string.", "examples": [ "2025-01-15T10:30:00Z" ] } }, "type": "object", "required": [ "timestamp" ], "title": "MonitorCompletionEvent", "description": "Emitted when a monitor execution ran but detected no material changes.\n\nOnly returned when `include_completions=true` is passed to the list events\nendpoint. Useful for auditing execution history alongside content events." }, "MonitorErrorEvent": { "properties": { "event_type": { "type": "string", "enum": [ "error" ], "const": "error", "title": "Event Type", "description": "Discriminant for the error event variant.", "default": "error" }, "error_message": { "type": "string", "title": "Error Message", "description": "Human-readable description of the failure." }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp", "description": "Timestamp of when the monitor execution failed, as an RFC 3339 string.", "examples": [ "2025-01-15T10:30:00Z" ] } }, "type": "object", "required": [ "error_message", "timestamp" ], "title": "MonitorErrorEvent", "description": "Emitted when a monitor execution failed (e.g. payment or quota error).\n\nAlways included in the events list regardless of `include_completions`." }, "MonitorEventStreamEvent": { "properties": { "event_id": { "type": "string", "title": "Event Id", "description": "Stable identifier for this event. Safe to use for client-side deduplication across pagination and retries." }, "event_group_id": { "type": "string", "title": "Event Group Id", "description": "ID of the event group that owns this event." }, "event_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Event Date", "description": "Date when this event was produced. ISO 8601 date (YYYY-MM-DD) or partial (YYYY-MM or YYYY).", "examples": [ "2026-04-07" ] }, "event_type": { "type": "string", "enum": [ "event_stream" ], "const": "event_stream", "title": "Event Type", "description": "Discriminant for the event_stream event variant.", "default": "event_stream" }, "output": { "oneOf": [ { "$ref": "#/components/schemas/TaskRunTextOutput" }, { "$ref": "#/components/schemas/TaskRunJsonOutput" } ], "title": "Output", "description": "Text or JSON output describing the detected change.", "discriminator": { "propertyName": "type", "mapping": { "json": "#/components/schemas/TaskRunJsonOutput", "text": "#/components/schemas/TaskRunTextOutput" } } } }, "type": "object", "required": [ "event_id", "event_group_id", "event_date", "output" ], "title": "MonitorEventStreamEvent", "description": "Append-only event from an event_stream monitor.\n\nEach event represents a distinct material change detected since the\nprevious execution. Events are net-new relative to the cursor; clients\nshould treat them as an append-only log." }, "MonitorEventStreamResponseSettings": { "properties": { "query": { "type": "string", "title": "Query", "description": "The search query being monitored.", "examples": [ "Extract recent news about AI" ] }, "output_schema": { "anyOf": [ { "$ref": "#/components/schemas/JsonSchema" }, { "type": "null" } ], "description": "JSON schema that constrains and structures the event output. When set, events are returned as JSON objects matching this schema." }, "include_backfill": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Include Backfill", "description": "If true, the first execution returns a sample of recent historical events matching the query (preview only \u2014 not exhaustive). If false or omitted, only events from the monitor's creation date onward are returned. Subsequent executions are always incremental." }, "advanced_settings": { "anyOf": [ { "$ref": "#/components/schemas/AdvancedMonitorSettings" }, { "type": "null" } ], "description": "Advanced monitor configuration." } }, "type": "object", "required": [ "query" ], "title": "MonitorEventStreamResponseSettings", "description": "Type-specific response fields for an `event_stream` monitor." }, "MonitorEventStreamSettings": { "properties": { "query": { "type": "string", "title": "Query", "description": "Search query to monitor for material changes.", "examples": [ "Extract recent news about AI" ] }, "output_schema": { "anyOf": [ { "$ref": "#/components/schemas/JsonSchema" }, { "type": "null" } ], "description": "JSON schema that constrains and structures the event output. When set, events are returned as JSON objects matching this schema instead of free-form text." }, "include_backfill": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Include Backfill", "description": "If true, the first execution returns a sample of recent historical events matching the query (preview only \u2014 not exhaustive). If false or omitted, only events from the monitor's creation date onward are returned. Subsequent executions are always incremental." }, "advanced_settings": { "anyOf": [ { "$ref": "#/components/schemas/AdvancedMonitorSettings" }, { "type": "null" } ], "description": "Advanced monitor configuration." } }, "type": "object", "required": [ "query" ], "title": "MonitorEventStreamSettings", "description": "Type-specific settings for an `event_stream` monitor." }, "MonitorMemoryEvent": { "properties": { "event_id": { "type": "string", "title": "Event Id", "description": "ID of the monitor event." }, "event_group_id": { "type": "string", "title": "Event Group Id", "description": "ID of the execution that produced this event." }, "detected_at": { "type": "string", "format": "date-time", "title": "Detected At", "description": "When the event was detected, as an RFC 3339 timestamp." }, "excerpt": { "type": "string", "title": "Excerpt", "description": "Excerpt of the monitor event. May be truncated." } }, "type": "object", "required": [ "event_id", "event_group_id", "detected_at", "excerpt" ], "title": "MonitorMemoryEvent" }, "MonitorMemoryResult": { "properties": { "kind": { "type": "string", "const": "monitor", "title": "Kind", "default": "monitor" }, "id": { "type": "string", "title": "Id", "description": "ID of the monitor." }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "When the monitor last ran, as an RFC 3339 timestamp." }, "input_excerpt": { "type": "string", "title": "Input Excerpt", "description": "Preview of the monitor's query. May be truncated." }, "status": { "type": "string", "enum": [ "active", "cancelled" ], "title": "Status", "description": "Current status of the monitor." }, "matched_events": { "items": { "$ref": "#/components/schemas/MonitorMemoryEvent" }, "type": "array", "title": "Matched Events", "description": "Detected events matching the retrieval query, ordered by relevance with more recent events favored. For an empty query, events are ordered by recency." } }, "type": "object", "required": [ "id", "updated_at", "input_excerpt", "status" ], "title": "MonitorMemoryResult" }, "MonitorResponse": { "properties": { "type": { "type": "string", "enum": [ "event_stream", "snapshot" ], "title": "Type", "description": "The type of monitor.", "examples": [ "event_stream", "snapshot" ] }, "monitor_id": { "type": "string", "title": "Monitor ID", "description": "ID of the monitor." }, "status": { "type": "string", "enum": [ "active", "cancelled" ], "title": "Status", "description": "Status of the monitor.", "examples": [ "active", "cancelled" ] }, "frequency": { "type": "string", "title": "Frequency", "description": "Frequency of the monitor. Format: '' where unit is 'h' (hours), 'd' (days), or 'w' (weeks). Must be between 1h and 30d (inclusive).", "examples": [ "1h", "12h", "1d", "7d", "30d" ] }, "processor": { "type": "string", "enum": [ "lite", "base" ], "title": "Processor", "description": "Processor to use for the monitor. `lite` is faster and cheaper; `base` performs more thorough analysis at higher cost and latency. Defaults to `lite`.", "examples": [ "lite", "base" ] }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/MonitorWebhook" }, { "type": "null" } ], "description": "Webhook configuration for the monitor." }, "metadata": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "User-provided metadata stored with the monitor and echoed back in webhook notifications and GET responses, so you can map events to objects in your application. Keys: max 16 chars; values: max 512 chars.", "examples": [ { "slack_thread_id": "1234567890.123456", "user_id": "U123ABC" } ] }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Timestamp of the creation of the monitor, as an RFC 3339 string.", "examples": [ "2025-01-15T10:30:00Z" ] }, "last_run_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Run At", "description": "Timestamp of the last run for the monitor, as an RFC 3339 string.", "examples": [ "2025-01-15T10:30:00Z" ] }, "settings": { "anyOf": [ { "$ref": "#/components/schemas/MonitorEventStreamResponseSettings" }, { "$ref": "#/components/schemas/MonitorSnapshotResponseSettings" } ], "title": "Settings", "description": "Type-specific configuration. Shape is determined by `type`: `MonitorEventStreamResponseSettings` for `event_stream`, `MonitorSnapshotResponseSettings` for `snapshot`." }, "output": { "anyOf": [ { "$ref": "#/components/schemas/MonitorSnapshotOutput" }, { "type": "null" } ], "description": "Runtime output state. Present only for `snapshot` monitors; `null` for `event_stream` monitors." } }, "type": "object", "required": [ "type", "monitor_id", "status", "frequency", "processor", "created_at", "settings" ], "title": "MonitorResponse", "description": "Response object for a monitor.\n\nThe `type` field at the root determines the concrete shape of `settings`:\n`event_stream` uses `MonitorEventStreamResponseSettings`, and `snapshot`\nuses `MonitorSnapshotResponseSettings`. Snapshot monitors also carry an\n`output` field (`MonitorSnapshotOutput`) with the latest computed state." }, "MonitorSnapshotEvent": { "properties": { "event_id": { "type": "string", "title": "Event Id", "description": "Stable identifier for this event. Safe to use for client-side deduplication across pagination and retries." }, "event_group_id": { "type": "string", "title": "Event Group Id", "description": "ID of the event group that owns this event." }, "event_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Event Date", "description": "Date when this event was produced. ISO 8601 date (YYYY-MM-DD) or partial (YYYY-MM or YYYY).", "examples": [ "2026-04-07" ] }, "event_type": { "type": "string", "enum": [ "snapshot" ], "const": "snapshot", "title": "Event Type", "description": "Discriminant for the snapshot event variant.", "default": "snapshot" }, "changed_output": { "oneOf": [ { "$ref": "#/components/schemas/TaskRunTextOutput" }, { "$ref": "#/components/schemas/TaskRunJsonOutput" } ], "title": "Changed Output", "description": "Partial output containing only the fields that changed since the previous execution, each with its `basis` (reasoning and citations).", "discriminator": { "propertyName": "type", "mapping": { "json": "#/components/schemas/TaskRunJsonOutput", "text": "#/components/schemas/TaskRunTextOutput" } } }, "previous_output": { "oneOf": [ { "$ref": "#/components/schemas/TaskRunTextOutput" }, { "$ref": "#/components/schemas/TaskRunJsonOutput" } ], "title": "Previous Output", "description": "The full output from the prior run, including all fields and basis.", "discriminator": { "propertyName": "type", "mapping": { "json": "#/components/schemas/TaskRunJsonOutput", "text": "#/components/schemas/TaskRunTextOutput" } } } }, "type": "object", "required": [ "event_id", "event_group_id", "event_date", "changed_output", "previous_output" ], "title": "MonitorSnapshotEvent", "description": "Snapshot diff event emitted when a monitored task run's output changes.\n\n`changed_output` contains only the fields that changed since the previous execution,\nalong with their `basis` (reasoning + citations). `previous_output` holds\nthe complete output from the prior run for comparison." }, "MonitorSnapshotOutput": { "properties": { "latest_snapshot": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/TaskRunTextOutput" }, { "$ref": "#/components/schemas/TaskRunJsonOutput" } ], "discriminator": { "propertyName": "type", "mapping": { "json": "#/components/schemas/TaskRunJsonOutput", "text": "#/components/schemas/TaskRunTextOutput" } } }, { "type": "null" } ], "title": "Latest Snapshot", "description": "Task run output from the most recent completed execution of this snapshot monitor \u2014 same structure as the output of the original task run the monitor was created from. `null` until the first run completes." } }, "type": "object", "title": "MonitorSnapshotOutput", "description": "Runtime output state for a `snapshot` monitor." }, "MonitorSnapshotResponseSettings": { "properties": { "task_run_id": { "type": "string", "title": "Task Run Id", "description": "ID of the task run used as the monitoring baseline." }, "query": { "type": "string", "title": "Query", "description": "The original task input from the baseline task run that this monitor tracks.", "examples": [ "Extract recent news about AI" ] }, "output_schema": { "anyOf": [ { "$ref": "#/components/schemas/JsonSchema" }, { "type": "null" } ], "description": "JSON schema derived from the baseline task run that constrains and structures the event output." } }, "type": "object", "required": [ "task_run_id", "query" ], "title": "MonitorSnapshotResponseSettings", "description": "Configuration settings for a `snapshot` monitor." }, "MonitorSnapshotSettings": { "properties": { "task_run_id": { "type": "string", "title": "Task Run Id", "description": "Task run ID whose output becomes the data and schema for the monitor." } }, "type": "object", "required": [ "task_run_id" ], "title": "MonitorSnapshotSettings", "description": "Type-specific settings for a `snapshot` monitor." }, "MonitorWebhook": { "properties": { "url": { "type": "string", "title": "Url", "description": "URL for the webhook.", "examples": [ "https://example.com/webhook" ] }, "event_types": { "items": { "type": "string", "enum": [ "monitor.event.detected", "monitor.execution.completed", "monitor.execution.failed" ] }, "type": "array", "title": "Event Types", "description": "Event types to send the webhook notifications for." } }, "type": "object", "required": [ "url" ], "title": "MonitorWebhook", "description": "Webhook configuration for a monitor." }, "OutputTokensDetails": { "additionalProperties": true, "description": "A detailed breakdown of the output tokens.", "properties": { "reasoning_tokens": { "title": "Reasoning Tokens", "type": "integer" } }, "required": [ "reasoning_tokens" ], "title": "OutputTokensDetails", "type": "object" }, "PaginatedMonitorEvents": { "properties": { "events": { "items": { "oneOf": [ { "$ref": "#/components/schemas/MonitorEventStreamEvent" }, { "$ref": "#/components/schemas/MonitorSnapshotEvent" }, { "$ref": "#/components/schemas/MonitorCompletionEvent" }, { "$ref": "#/components/schemas/MonitorErrorEvent" } ], "discriminator": { "propertyName": "event_type", "mapping": { "completion": "#/components/schemas/MonitorCompletionEvent", "error": "#/components/schemas/MonitorErrorEvent", "event_stream": "#/components/schemas/MonitorEventStreamEvent", "snapshot": "#/components/schemas/MonitorSnapshotEvent" } } }, "type": "array", "title": "Events", "description": "Monitor events returned by this request, ordered newest first." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Pass as `cursor` to retrieve more events. Absent when there are no more events." }, "warnings": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Warning" }, "type": "array" }, { "type": "null" } ], "title": "Warnings", "description": "Execution caveats for this page of events, e.g. compute limits." } }, "type": "object", "required": [ "events" ], "title": "PaginatedMonitorEvents", "description": "Paginated list of monitor events, newest first." }, "PaginatedMonitorResponse": { "properties": { "monitors": { "items": { "$ref": "#/components/schemas/MonitorResponse" }, "type": "array", "title": "Monitors", "description": "List of monitors for the current page." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "Opaque pagination token. Pass as `cursor` to retrieve the next page. Absent when there are no more pages." } }, "type": "object", "required": [ "monitors" ], "title": "PaginatedMonitorResponse", "description": "Paginated list of monitors." }, "PromptTokensDetails": { "additionalProperties": true, "description": "Breakdown of tokens used in the prompt.", "properties": { "audio_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Audio Tokens" }, "cached_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Cached Tokens" } }, "title": "PromptTokensDetails", "type": "object" }, "Response": { "additionalProperties": true, "description": "A response from the `parallel` model. A completed response contains a\nsingle assistant message whose text is annotated with URL citations\ngrounding the answer.", "properties": { "id": { "title": "Id", "type": "string" }, "created_at": { "title": "Created At", "type": "number" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ResponseError" }, { "type": "null" } ], "default": null }, "incomplete_details": { "anyOf": [ { "$ref": "#/components/schemas/IncompleteDetails" }, { "type": "null" } ], "default": null }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Instructions" }, "metadata": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Metadata" }, "model": { "const": "parallel", "default": "parallel", "title": "Model", "type": "string" }, "object": { "const": "response", "title": "Object", "type": "string" }, "output": { "items": { "$ref": "#/components/schemas/ResponseOutputMessage" }, "title": "Output", "type": "array" }, "parallel_tool_calls": { "title": "Parallel Tool Calls", "type": "boolean" }, "temperature": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Temperature" }, "tool_choice": { "default": "auto", "title": "Tool Choice", "type": "string" }, "tools": { "default": [], "items": {}, "title": "Tools", "type": "array" }, "top_p": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Top P" }, "background": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Background" }, "completed_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Completed At" }, "conversation": { "default": null, "title": "Conversation", "type": "null" }, "max_output_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Max Output Tokens" }, "max_tool_calls": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Max Tool Calls" }, "moderation": { "anyOf": [ { "$ref": "#/components/schemas/Moderation" }, { "type": "null" } ], "default": null }, "previous_response_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Previous Response Id" }, "prompt": { "default": null, "title": "Prompt", "type": "null" }, "prompt_cache_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Prompt Cache Key" }, "prompt_cache_retention": { "anyOf": [ { "enum": [ "in_memory", "24h" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Prompt Cache Retention" }, "reasoning": { "anyOf": [ { "$ref": "#/components/schemas/ResponseReasoningConfig" }, { "type": "null" } ], "default": null }, "safety_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Safety Identifier" }, "service_tier": { "anyOf": [ { "enum": [ "auto", "default", "flex", "scale", "priority" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Service Tier" }, "status": { "anyOf": [ { "enum": [ "completed", "failed", "in_progress", "cancelled", "queued", "incomplete" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" }, "text": { "anyOf": [ { "$ref": "#/components/schemas/ResponseTextConfig" }, { "type": "null" } ], "default": null }, "top_logprobs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Top Logprobs" }, "truncation": { "anyOf": [ { "enum": [ "auto", "disabled" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Truncation" }, "usage": { "anyOf": [ { "$ref": "#/components/schemas/ResponseUsage" }, { "type": "null" } ], "default": null }, "user": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "User" } }, "required": [ "id", "created_at", "object", "output", "parallel_tool_calls" ], "title": "Response", "type": "object" }, "ResponseCreateRequest": { "properties": { "model": { "type": "string", "title": "Model", "description": "The model to run. `parallel` is the only supported value (matched case-insensitively); any other value is rejected. To trade response time for answer quality, set `reasoning.effort` (low/medium/high) rather than changing the model name.", "examples": [ "parallel" ] }, "input": { "anyOf": [ { "type": "string" }, { "items": { "$ref": "#/components/schemas/ResponseInputMessage" }, "type": "array" } ], "title": "Input", "description": "The input to generate a response for: a plain string, or a list of role/content messages that includes at least one `user` message. Must be non-empty, and only text content is supported. `input` and `instructions` together may total at most 20,000 characters.", "examples": [ "What are the latest developments in fusion energy?" ] }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions", "description": "System instructions for the model." }, "previous_response_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Response Id", "description": "ID of a previous response to use as conversation context." }, "stream": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Stream", "description": "Whether to stream the response." }, "text": { "anyOf": [ { "$ref": "#/components/schemas/ResponseTextConfig" }, { "type": "null" } ], "description": "Configuration for text output, including structured output." }, "metadata": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object", "maxProperties": 16 }, { "type": "null" } ], "title": "Metadata", "description": "Arbitrary key-value pairs, echoed back on the Response object. Useful for tagging requests. At most 16 keys; keys up to 64 characters, values up to 512 characters." }, "reasoning": { "anyOf": [ { "$ref": "#/components/schemas/ResponseReasoningConfig" }, { "type": "null" } ], "description": "Reasoning configuration. `effort` (low/medium/high) controls how much research is performed; defaults to `medium`." }, "background": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Background", "description": "Background mode is not supported: requests with `background=true` are rejected with a 422 validation error. Use the Task API (POST /v1/tasks/runs) for long-running work." } }, "type": "object", "required": [ "model", "input" ], "title": "ResponseCreateRequest", "description": "Request body for the Responses API (`POST /v1/responses`).\n\nOpenAI-Responses-compatible: point a standard OpenAI client at\n`https://api.parallel.ai/v1` with your Parallel API key and set `model` to\n`parallel`. The fields below are the ones Parallel acts on; other OpenAI\nrequest fields (`tools`, `tool_choice`, `temperature`, `top_p`,\n`max_output_tokens`, `parallel_tool_calls`, `truncation`, `store`, `user`,\n`include`) are accepted for compatibility but have no effect." }, "ResponseError": { "additionalProperties": true, "description": "Details of a failed response.", "properties": { "code": { "const": "server_error", "description": "Error code; currently always \"server_error\".", "title": "Code", "type": "string" }, "message": { "title": "Message", "type": "string" } }, "required": [ "code", "message" ], "title": "ResponseError", "type": "object" }, "ResponseFormatJSONObject": { "additionalProperties": true, "description": "JSON object response format.\n\nAn older method of generating JSON responses.\nUsing `json_schema` is recommended for models that support it. Note that the\nmodel will not generate JSON without a system or user message instructing it\nto do so.", "properties": { "type": { "const": "json_object", "title": "Type", "type": "string" } }, "required": [ "type" ], "title": "ResponseFormatJSONObject", "type": "object" }, "ResponseFormatJSONSchema": { "properties": { "json_schema": { "$ref": "#/components/schemas/JSONSchema" }, "type": { "type": "string", "const": "json_schema", "title": "Type" } }, "type": "object", "required": [ "json_schema", "type" ], "title": "ResponseFormatJSONSchema", "description": "JSON Schema response format.\n\nUsed to generate structured JSON responses.\nLearn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs)." }, "ResponseFormatText": { "additionalProperties": true, "description": "Default response format. Used to generate text responses.", "properties": { "type": { "const": "text", "title": "Type", "type": "string" } }, "required": [ "type" ], "title": "ResponseFormatText", "type": "object" }, "ResponseFormatTextJSONSchemaConfig": { "additionalProperties": true, "description": "JSON Schema output format: the response's output text conforms to `schema`.", "properties": { "name": { "title": "Name", "type": "string" }, "schema": { "additionalProperties": true, "title": "Schema", "type": "object" }, "type": { "const": "json_schema", "title": "Type", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "strict": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Strict" } }, "required": [ "name", "schema", "type" ], "title": "ResponseFormatTextJSONSchemaConfig", "type": "object" }, "ResponseInputContentPart": { "properties": { "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type", "description": "The content part type. Supported: `input_text`, `output_text`, and `text`. Multimodal types (`input_image`, `input_audio`, `input_file`) are rejected with a 422 error." }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Text", "description": "The text payload, when the part carries one." } }, "type": "object", "title": "ResponseInputContentPart", "description": "A single content part of a message, e.g.\n`{\"text\": \"hi\", \"type\": \"input_text\"}`. Only text parts are supported;\nrequests containing image, audio, or file parts fail with a 422 error." }, "ResponseInputMessage": { "properties": { "role": { "type": "string", "enum": [ "user", "assistant", "system", "developer" ], "title": "Role", "description": "The role of the message author." }, "content": { "anyOf": [ { "type": "string" }, { "items": { "$ref": "#/components/schemas/ResponseInputContentPart" }, "type": "array" } ], "title": "Content", "description": "Text content of the message. Either a string or a list of content parts (`{text, type}` objects) for OpenAI SDK clients." } }, "type": "object", "required": [ "role", "content" ], "title": "ResponseInputMessage", "description": "A single input message for the Responses API.\n\n`content` accepts either a bare string (`\"hi\"`) or the canonical OpenAI\nlist-of-parts (`[{\"text\": \"hi\", \"type\": \"input_text\"}]`)." }, "ResponseOutputMessage": { "additionalProperties": true, "description": "An assistant message produced by the model.", "properties": { "id": { "title": "Id", "type": "string" }, "content": { "items": { "$ref": "#/components/schemas/ResponseOutputText" }, "title": "Content", "type": "array" }, "role": { "const": "assistant", "title": "Role", "type": "string" }, "status": { "enum": [ "in_progress", "completed", "incomplete" ], "title": "Status", "type": "string" }, "type": { "const": "message", "title": "Type", "type": "string" }, "phase": { "anyOf": [ { "enum": [ "commentary", "final_answer" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Phase" } }, "required": [ "id", "content", "role", "status", "type" ], "title": "ResponseOutputMessage", "type": "object" }, "ResponseOutputText": { "additionalProperties": true, "description": "A text content part of an output message. `annotations` carries the URL\ncitations grounding the answer.", "properties": { "annotations": { "items": { "$ref": "#/components/schemas/AnnotationURLCitation" }, "title": "Annotations", "type": "array" }, "text": { "title": "Text", "type": "string" }, "type": { "const": "output_text", "title": "Type", "type": "string" }, "logprobs": { "anyOf": [ { "items": { "$ref": "#/components/schemas/openai__types__responses__response_output_text__Logprob" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Logprobs" } }, "required": [ "annotations", "text", "type" ], "title": "ResponseOutputText", "type": "object" }, "ResponseReasoningConfig": { "description": "Reasoning configuration (OpenAI-compatible subset).", "properties": { "effort": { "anyOf": [ { "enum": [ "low", "medium", "high" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "Controls how much research is performed, trading response time for answer quality. Defaults to `medium` when omitted.", "examples": [ "high" ], "title": "Effort" } }, "title": "ResponseReasoningConfig", "type": "object" }, "ResponseTextConfig": { "additionalProperties": true, "description": "Text output configuration. By default the response is plain text; for\nstructured output set `format` to\n`{\"type\": \"json_schema\", \"name\": ..., \"schema\": {...}}`. The `json_object`\nformat is accepted for compatibility but produces plain text.", "properties": { "format": { "anyOf": [ { "$ref": "#/components/schemas/ResponseFormatText" }, { "$ref": "#/components/schemas/ResponseFormatTextJSONSchemaConfig" }, { "$ref": "#/components/schemas/ResponseFormatJSONObject" }, { "type": "null" } ], "default": null, "title": "Format" }, "verbosity": { "anyOf": [ { "enum": [ "low", "medium", "high" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Verbosity" } }, "title": "ResponseTextConfig", "type": "object" }, "ResponseUsage": { "additionalProperties": true, "description": "Estimated token usage, populated for OpenAI SDK compatibility. Counts\nare approximate; Parallel bills per request, not per token.", "properties": { "input_tokens": { "title": "Input Tokens", "type": "integer" }, "input_tokens_details": { "$ref": "#/components/schemas/InputTokensDetails" }, "output_tokens": { "title": "Output Tokens", "type": "integer" }, "output_tokens_details": { "$ref": "#/components/schemas/OutputTokensDetails" }, "total_tokens": { "title": "Total Tokens", "type": "integer" } }, "required": [ "input_tokens", "input_tokens_details", "output_tokens", "output_tokens_details", "total_tokens" ], "title": "ResponseUsage", "type": "object" }, "SourcePolicy": { "properties": { "include_domains": { "items": { "type": "string" }, "type": "array", "title": "Include Domains", "description": "List of domains to restrict the results to. If specified, only sources from these domains will be included. Accepts plain domains (e.g., example.com, subdomain.example.gov) or bare domain extension starting with a period (e.g., .gov, .edu, .co.uk). The combined number of domains in include_domains and exclude_domains cannot exceed 200.", "examples": [ [ "wikipedia.org", "usa.gov", ".edu" ] ] }, "exclude_domains": { "items": { "type": "string" }, "type": "array", "title": "Exclude Domains", "description": "List of domains to exclude from results. If specified, sources from these domains will be excluded. Accepts plain domains (e.g., example.com, subdomain.example.gov) or bare domain extension starting with a period (e.g., .gov, .edu, .co.uk). The combined number of domains in include_domains and exclude_domains cannot exceed 200.", "examples": [ [ "reddit.com", "x.com", ".ai" ] ] }, "after_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "After Date", "description": "Optional start date for filtering search results. Results will be limited to content published on or after this date. Provided as an RFC 3339 date string (YYYY-MM-DD).", "examples": [ "2024-01-01" ] } }, "type": "object", "title": "SourcePolicy", "description": "Source policy for web search results.\n\nThis policy governs which sources are allowed/disallowed in results." }, "TaskAdvancedSettings": { "properties": { "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location", "description": "ISO 3166-1 alpha-2 country code for geo-targeted search results.", "examples": [ "us", "gb", "de", "jp" ] } }, "type": "object", "title": "TaskAdvancedSettings", "description": "Advanced search configuration for a task run." }, "TaskGroupResponse": { "properties": { "taskgroup_id": { "type": "string", "title": "Taskgroup ID", "description": "ID of the group." }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "User-provided metadata stored with the group." }, "status": { "$ref": "#/components/schemas/TaskGroupStatus", "description": "Status of the group." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At", "description": "Timestamp of the creation of the group, as an RFC 3339 string.", "examples": [ "2025-04-24T18:56:22.513132Z" ] } }, "type": "object", "required": [ "taskgroup_id", "status", "created_at" ], "title": "TaskGroupResponse", "description": "Response object for a task group, including its status and metadata." }, "TaskGroupRunRequest": { "properties": { "default_task_spec": { "anyOf": [ { "$ref": "#/components/schemas/TaskSpec" }, { "type": "null" } ], "description": "Default task spec to use for the runs. If task_spec is specified in a run, it overrides this default." }, "inputs": { "items": { "$ref": "#/components/schemas/TaskRunInput" }, "type": "array", "title": "Inputs", "description": "List of task runs to execute. Up to 1,000 runs can be specified per request. If you'd like to add more runs, split them across multiple TaskGroup POST requests." } }, "type": "object", "required": [ "inputs" ], "title": "TaskGroupRunRequest", "description": "Request to initiate new task runs in a task group." }, "TaskGroupRunResponse": { "properties": { "status": { "$ref": "#/components/schemas/TaskGroupStatus", "description": "Status of the group." }, "run_ids": { "items": { "type": "string" }, "type": "array", "title": "Run IDs", "description": "IDs of the newly created runs." }, "run_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Run Cursor", "description": "Cursor for these runs in the run stream at taskgroup/runs?last_event_id=. Empty for the first runs in the group." }, "event_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Event Cursor", "description": "Cursor for these runs in the event stream at taskgroup/events?last_event_id=. Empty for the first runs in the group." } }, "type": "object", "required": [ "status", "run_ids", "run_cursor", "event_cursor" ], "title": "TaskGroupRunResponse", "description": "Response from adding new task runs to a task group." }, "TaskGroupStatus": { "properties": { "num_task_runs": { "type": "integer", "title": "Num Task Runs", "description": "Number of task runs in the group." }, "task_run_status_counts": { "additionalProperties": { "type": "integer" }, "propertyNames": { "enum": [ "queued", "action_required", "running", "completed", "failed", "cancelling", "cancelled" ] }, "type": "object", "title": "Task Run Status Counts", "description": "Number of task runs with each status." }, "is_active": { "type": "boolean", "title": "Is Active", "description": "True if at least one run in the group is currently active, i.e. status is one of {'cancelling', 'queued', 'running'}." }, "status_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status Message", "description": "Human-readable status message for the group." }, "modified_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Modified At", "description": "Timestamp of the last status update to the group, as an RFC 3339 string.", "examples": [ "2025-04-24T18:56:22.513132Z" ] } }, "type": "object", "required": [ "num_task_runs", "task_run_status_counts", "is_active", "status_message", "modified_at" ], "title": "TaskGroupStatus", "description": "Status of a task group." }, "TaskGroupStatusEvent": { "properties": { "type": { "type": "string", "const": "task_group_status", "title": "Type", "description": "Event type; always 'task_group_status'." }, "event_id": { "type": "string", "title": "Event ID", "description": "Cursor to resume the event stream." }, "status": { "$ref": "#/components/schemas/TaskGroupStatus", "description": "Task group status object." } }, "type": "object", "required": [ "type", "event_id", "status" ], "title": "TaskGroupStatusEvent", "description": "Event indicating an update to group status." }, "TaskMemoryResult": { "properties": { "kind": { "type": "string", "const": "task", "title": "Kind", "default": "task" }, "id": { "type": "string", "title": "Id", "description": "ID of the task run." }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "When the run completed, as an RFC 3339 timestamp." }, "input_excerpt": { "type": "string", "title": "Input Excerpt", "description": "Preview of the run's input. May be truncated." }, "output_excerpt": { "type": "string", "title": "Output Excerpt", "description": "Preview of the run's output. May be truncated." } }, "type": "object", "required": [ "id", "updated_at", "input_excerpt", "output_excerpt" ], "title": "TaskMemoryResult" }, "TaskRun": { "properties": { "run_id": { "type": "string", "title": "Run ID", "description": "ID of the task run.", "examples": [ "trun_e0083b6aac0544eb8686e8d2a76533d2" ] }, "interaction_id": { "type": "string", "title": "Interaction ID", "description": "Identifier for this interaction. Pass this value as `previous_interaction_id` to reuse context for a future request.", "examples": [ "trun_e0083b6aac0544eb8686e8d2a76533d2" ] }, "status": { "type": "string", "enum": [ "queued", "action_required", "running", "completed", "failed", "cancelling", "cancelled" ], "title": "Status", "description": "Status of the run.", "examples": [ "queued", "action_required", "running", "completed", "failed", "cancelling", "cancelled" ] }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether the run is currently active, i.e. status is one of {'cancelling', 'queued', 'running'}." }, "warnings": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Warning" }, "type": "array" }, { "type": "null" } ], "title": "Warnings", "description": "Warnings for the run, if any.", "examples": [ [] ] }, "error": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "null" } ], "description": "Error for the run, present only if status is 'failed'." }, "processor": { "type": "string", "title": "Processor", "description": "Processor used for the run.", "examples": [ "base" ] }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "User-provided metadata stored with the run.", "examples": [ {} ] }, "taskgroup_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Taskgroup ID", "description": "ID of the taskgroup to which the run belongs." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At", "description": "Timestamp of the creation of the task, as an RFC 3339 string.", "examples": [ "2025-04-24T18:56:22.513132Z" ] }, "modified_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Modified At", "description": "Timestamp of the last modification to the task, as an RFC 3339 string.", "examples": [ "2025-04-24T18:56:22.513132Z" ] } }, "type": "object", "required": [ "run_id", "interaction_id", "status", "is_active", "processor", "created_at", "modified_at" ], "title": "TaskRun", "description": "Status of a task run." }, "TaskRunEvent": { "properties": { "type": { "type": "string", "const": "task_run.state", "title": "Type", "description": "Event type; always 'task_run.state'." }, "event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Event ID", "description": "Cursor to resume the event stream. Always empty for non Task Group runs." }, "input": { "anyOf": [ { "$ref": "#/components/schemas/TaskRunInput" }, { "type": "null" } ], "description": "Input to the run; included only if requested." }, "run": { "$ref": "#/components/schemas/TaskRun", "description": "Task run object." }, "output": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/TaskRunTextOutput" }, { "$ref": "#/components/schemas/TaskRunJsonOutput" } ], "discriminator": { "propertyName": "type", "mapping": { "json": "#/components/schemas/TaskRunJsonOutput", "text": "#/components/schemas/TaskRunTextOutput" } } }, { "type": "null" } ], "title": "Output", "description": "Output from the run; included only if requested and if status == `completed`." } }, "type": "object", "required": [ "type", "event_id", "run" ], "title": "TaskRunEvent", "description": "Event when a task run transitions to a non-active status.\n\nMay indicate completion, cancellation, or failure." }, "TaskRunInput": { "properties": { "processor": { "type": "string", "title": "Processor", "description": "Processor to use for the task.", "examples": [ "base" ] }, "metadata": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "User-provided metadata stored with the run. Keys and values must be strings with a maximum length of 16 and 512 characters respectively." }, "memory_scope_key": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, { "type": "null" } ], "title": "Memory Scope Key", "description": "User-provided key identifying the memory scope to use. Omit to use personal memory, if available." }, "source_policy": { "anyOf": [ { "$ref": "#/components/schemas/SourcePolicy" }, { "type": "null" } ], "description": "Optional source policy governing preferred and disallowed domains in web search results." }, "advanced_settings": { "anyOf": [ { "$ref": "#/components/schemas/TaskAdvancedSettings" }, { "type": "null" } ], "description": "Advanced search configuration for the task run." }, "task_spec": { "anyOf": [ { "$ref": "#/components/schemas/TaskSpec" }, { "type": "null" } ], "description": "Task specification. If unspecified, defaults to auto output schema." }, "input": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" } ], "title": "Input", "description": "Input to the task, either text or a JSON object.", "examples": [ "What was the GDP of France in 2023?", "{\"country\": \"France\", \"year\": 2023}" ] }, "previous_interaction_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Interaction Id", "description": "Interaction ID to use as context for this request." }, "mcp_servers": { "anyOf": [ { "items": { "$ref": "#/components/schemas/McpServer" }, "type": "array" }, { "type": "null" } ], "title": "Mcp Servers", "description": "Optional list of MCP servers to use for the run." }, "enable_events": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enable Events", "description": "Controls tracking of task run execution progress. When set to true, progress events are recorded and can be accessed via the [Task Run events](https://docs.parallel.ai/api-reference) endpoint. When false, no progress events are tracked. Note that progress tracking cannot be enabled after a run has been created. The flag is set to true by default for premium processors (pro and above)." }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "null" } ], "description": "Callback URL (webhook endpoint) that will receive an HTTP POST when the run completes. \nThis feature is not available via the Python SDK." } }, "type": "object", "required": [ "processor", "input" ], "title": "TaskRunInput", "description": "Request to run a task." }, "TaskRunJsonOutput": { "properties": { "basis": { "items": { "$ref": "#/components/schemas/FieldBasis" }, "type": "array", "title": "Basis", "description": "Basis for each top-level field in the JSON output. Per-list-element basis entries are available only when the `parallel-beta: field-basis-2025-11-25` header is supplied." }, "type": { "type": "string", "const": "json", "title": "Type", "description": "The type of output being returned, as determined by the output schema of the task spec." }, "mcp_tool_calls": { "anyOf": [ { "items": { "$ref": "#/components/schemas/McpToolCall" }, "type": "array" }, { "type": "null" } ], "title": "Mcp Tool Calls", "description": "MCP tool calls made by the task." }, "beta_fields": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Beta Fields", "description": "Deprecated. mcp-server-2025-07-17 is now included directly in the output (e.g. mcp_tool_calls).", "deprecated": true }, "content": { "additionalProperties": true, "type": "object", "title": "Content", "description": "Output from the task as a native JSON object, as determined by the output schema of the task spec." }, "output_schema": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Output Schema", "description": "Output schema for the Task Run. Populated only if the task was executed with an auto schema." } }, "type": "object", "required": [ "basis", "type", "content" ], "title": "TaskRunJsonOutput", "description": "Output from a task that returns JSON." }, "TaskRunProgressMessageEvent": { "properties": { "type": { "type": "string", "enum": [ "task_run.progress_msg.plan", "task_run.progress_msg.search", "task_run.progress_msg.result", "task_run.progress_msg.tool_call", "task_run.progress_msg.exec_status" ], "title": "Type", "description": "Event type; always starts with 'task_run.progress_msg'." }, "message": { "type": "string", "title": "Message", "description": "Progress update message." }, "timestamp": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Timestamp", "description": "Timestamp of the message." } }, "type": "object", "required": [ "type", "message", "timestamp" ], "title": "TaskRunProgressMessageEvent", "description": "A message for a task run progress update." }, "TaskRunProgressStatsEvent": { "properties": { "type": { "type": "string", "const": "task_run.progress_stats", "title": "Type", "description": "Event type; always 'task_run.progress_stats'." }, "source_stats": { "$ref": "#/components/schemas/TaskRunSourceStats", "description": "Source stats describing progress so far." }, "progress_meter": { "type": "number", "title": "Progress Meter", "description": "Completion percentage of the task run. Ranges from 0 to 100 where 0 indicates no progress and 100 indicates completion." } }, "type": "object", "required": [ "type", "source_stats", "progress_meter" ], "title": "TaskRunProgressStatsEvent", "description": "A progress update for a task run." }, "TaskRunResult": { "properties": { "run": { "$ref": "#/components/schemas/TaskRun", "description": "Task run object with status 'completed'." }, "output": { "oneOf": [ { "$ref": "#/components/schemas/TaskRunTextOutput" }, { "$ref": "#/components/schemas/TaskRunJsonOutput" } ], "title": "Output", "description": "Output from the task conforming to the output schema.", "discriminator": { "propertyName": "type", "mapping": { "json": "#/components/schemas/TaskRunJsonOutput", "text": "#/components/schemas/TaskRunTextOutput" } } } }, "type": "object", "required": [ "run", "output" ], "title": "TaskRunResult", "description": "Result of a task run." }, "TaskRunSourceStats": { "properties": { "num_sources_considered": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Num Sources Considered", "description": "Number of sources considered in processing the task." }, "num_sources_read": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Num Sources Read", "description": "Number of sources read in processing the task." }, "sources_read_sample": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Sources Read Sample", "description": "A sample of URLs of sources read in processing the task." } }, "type": "object", "required": [ "num_sources_considered", "num_sources_read", "sources_read_sample" ], "title": "TaskRunSourceStats", "description": "Source stats for a task run." }, "TaskRunTextOutput": { "properties": { "basis": { "items": { "$ref": "#/components/schemas/FieldBasis" }, "type": "array", "title": "Basis", "description": "Basis for the output. The basis has a single field 'output'." }, "type": { "type": "string", "const": "text", "title": "Type", "description": "The type of output being returned, as determined by the output schema of the task spec." }, "mcp_tool_calls": { "anyOf": [ { "items": { "$ref": "#/components/schemas/McpToolCall" }, "type": "array" }, { "type": "null" } ], "title": "Mcp Tool Calls", "description": "MCP tool calls made by the task." }, "beta_fields": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Beta Fields", "description": "Deprecated. mcp-server-2025-07-17 is now included directly in the output (e.g. mcp_tool_calls).", "deprecated": true }, "content": { "type": "string", "title": "Content", "description": "Text output from the task." } }, "type": "object", "required": [ "basis", "type", "content" ], "title": "TaskRunTextOutput", "description": "Output from a task that returns text." }, "TaskSpec": { "properties": { "output_schema": { "anyOf": [ { "$ref": "#/components/schemas/JsonSchema" }, { "$ref": "#/components/schemas/TextSchema" }, { "$ref": "#/components/schemas/AutoSchema" }, { "type": "string" } ], "title": "Output Schema", "description": "JSON schema or text fully describing the desired output from the task. Descriptions of output fields will determine the form and content of the response. A bare string is equivalent to a text schema with the same description." }, "input_schema": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/JsonSchema" }, { "$ref": "#/components/schemas/TextSchema" }, { "type": "null" } ], "title": "Input Schema", "description": "Optional JSON schema or text description of expected input to the task. A bare string is equivalent to a text schema with the same description." } }, "type": "object", "required": [ "output_schema" ], "title": "TaskSpec", "description": "Specification for a task.\n\nAuto output schemas can be specified by setting `output_schema={\"type\":\"auto\"}`. Not\nspecifying a TaskSpec is the same as setting an auto output schema.\n\nFor convenience bare strings are also accepted as input or output schemas." }, "TextSchema": { "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "A text description of the desired output from the task.", "examples": [ "GDP in USD for the year, formatted like '$3.1 trillion (2023)'" ] }, "type": { "type": "string", "const": "text", "title": "Type", "description": "The type of schema being defined. Always `text`.", "default": "text" } }, "type": "object", "title": "TextSchema", "description": "Text description for a task input or output." }, "TopLogprob": { "additionalProperties": true, "properties": { "token": { "title": "Token", "type": "string" }, "bytes": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Bytes" }, "logprob": { "title": "Logprob", "type": "number" } }, "required": [ "token", "logprob" ], "title": "TopLogprob", "type": "object" }, "UpdateMonitorEventStreamSettings": { "properties": { "query": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Query", "description": "Updated search query for the monitor. Use this for minor updates to prompts and instructions only. Major changes to the query may lead to unexpected results in change detection, as the monitor compares new results with what was previously seen.", "examples": [ "Extract recent news about AI" ] }, "advanced_settings": { "anyOf": [ { "$ref": "#/components/schemas/AdvancedMonitorSettings" }, { "type": "null" } ], "description": "Advanced monitor configuration." } }, "type": "object", "title": "UpdateMonitorEventStreamSettings", "description": "Type-specific update settings for an `event_stream` monitor." }, "UpdateMonitorRequest": { "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "event_stream", "snapshot" ] }, { "type": "null" } ], "title": "Type", "description": "Type of the monitor being updated. Required when `settings` is provided; must be `event_stream` (snapshot monitors have no updatable type-specific settings).", "examples": [ "event_stream" ] }, "frequency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Frequency", "description": "Frequency of the monitor. Format: '' where unit is 'h' (hours), 'd' (days), or 'w' (weeks). Must be between 1h and 30d (inclusive).", "examples": [ "1h", "12h", "1d", "7d", "30d" ] }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/MonitorWebhook" }, { "type": "null" } ], "description": "Webhook to receive notifications about the monitor's execution." }, "metadata": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "User-provided metadata stored with the monitor and echoed back in webhook notifications and GET responses, so you can map events to objects in your application. Keys: max 16 chars; values: max 512 chars.", "examples": [ { "slack_thread_id": "1234567890.123456", "user_id": "U123ABC" } ] }, "settings": { "anyOf": [ { "$ref": "#/components/schemas/UpdateMonitorEventStreamSettings" }, { "type": "null" } ], "description": "Type-specific settings to update. Only valid when `type` is `event_stream`. Pass `settings.query` to update the prompt, or `null` for `settings.advanced_settings` to clear it." } }, "type": "object", "title": "UpdateMonitorRequest", "description": "Request body to update a monitor.\n\nOnly fields that are explicitly included in the request body are updated.\nPass `null` for `webhook` or `metadata` to clear those fields. To update\ntype-specific settings on an `event_stream` monitor, include `type` and\n`settings`; pass `settings.query` to update the prompt, or `null` for\n`settings.advanced_settings` to clear it. If `settings` is provided, `type`\nis required to identify the settings shape. The request must still include\nat least one field to update; empty updates fail validation." }, "UsageItem": { "properties": { "name": { "type": "string", "title": "Name", "description": "Name of the SKU.", "examples": [ "sku_search_additional_results", "sku_extract_excerpts" ] }, "count": { "type": "integer", "title": "Count", "description": "Count of the SKU.", "examples": [ 1 ] } }, "type": "object", "required": [ "name", "count" ], "title": "UsageItem", "description": "Usage item for a single operation." }, "V1ExcerptSettings": { "properties": { "max_chars_per_result": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Chars Per Result", "description": "Optional upper bound on the total number of characters to include per url. Excerpts may contain fewer characters than this limit to maximize relevance and token efficiency." } }, "additionalProperties": false, "type": "object", "title": "V1ExcerptSettings", "description": "Optional settings for returning relevant excerpts." }, "V1ExtractRequest": { "properties": { "urls": { "items": { "type": "string" }, "type": "array", "title": "Urls", "description": "URLs to extract content from. Up to 20 URLs." }, "objective": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Objective", "description": "As in SearchRequest, a natural-language description of the underlying question or goal driving the request. Used together with search_queries to focus excerpts on the most relevant content." }, "search_queries": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Search Queries", "description": "Optional keyword search queries, as in SearchRequest. Used together with objective to focus excerpts on the most relevant content." }, "max_chars_total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Chars Total", "description": "Upper bound on total characters across excerpts from all extracted results." }, "session_id": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Session Id", "description": "Session identifier to track calls across separate search and extract calls, to be used as part of a larger task. Specifying it may give better contextual results for subsequent API calls." }, "client_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Model", "description": "The model generating this request and consuming the results. Enables optimizations and tailors default settings for the model's capabilities.", "examples": [ "claude-opus-4-7", "gpt-5.4", "gemini-3.1-pro" ] }, "advanced_settings": { "anyOf": [ { "$ref": "#/components/schemas/AdvancedExtractSettings" }, { "type": "null" } ], "description": "Advanced configuration for fetch policy, excerpt settings, and full content settings. May impact result quality and latency unless used carefully. When omitted, excerpts are enabled and full content is disabled by default." } }, "additionalProperties": false, "type": "object", "required": [ "urls" ], "title": "V1ExtractRequest", "description": "Extract request." }, "V1ExtractResponse": { "properties": { "extract_id": { "type": "string", "title": "Extract Id", "description": "Extract request ID, e.g. `extract_cad0a6d2dec046bd95ae900527d880e7`" }, "results": { "items": { "$ref": "#/components/schemas/V1ExtractResult" }, "type": "array", "title": "Results", "description": "Successful extract results." }, "errors": { "items": { "$ref": "#/components/schemas/ExtractError" }, "type": "array", "title": "Errors", "description": "Extract errors: requested URLs not in the results." }, "warnings": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Warning" }, "type": "array" }, { "type": "null" } ], "title": "Warnings", "description": "Warnings for the extract request, if any." }, "usage": { "anyOf": [ { "items": { "$ref": "#/components/schemas/UsageItem" }, "type": "array" }, { "type": "null" } ], "title": "Usage", "description": "Usage metrics for the extract request." }, "session_id": { "type": "string", "title": "Session Id", "description": "Session identifier. Echoed back from the request if provided, otherwise generated by the server. Should be passed to future search and extract calls made by the agent as part of the same larger task.", "examples": [ "session_8a911eb27c7a4afaa20d0d9dc98d07c0" ] } }, "type": "object", "required": [ "extract_id", "results", "errors", "session_id" ], "title": "V1ExtractResponse", "description": "Extract response." }, "V1ExtractResult": { "properties": { "url": { "type": "string", "title": "Url", "description": "URL associated with the search result." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "description": "Title of the webpage, if available." }, "publish_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Publish Date", "description": "Publish date of the webpage in YYYY-MM-DD format, if available." }, "excerpts": { "items": { "type": "string" }, "type": "array", "title": "Excerpts", "description": "Relevant excerpted content from the URL, formatted as markdown." }, "full_content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Full Content", "description": "Full content from the URL formatted as markdown, if requested." } }, "type": "object", "required": [ "url", "excerpts" ], "title": "V1ExtractResult", "description": "Extract result for a single URL." }, "V1SearchRequest": { "properties": { "objective": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Objective", "description": "Natural-language description of the underlying question or goal driving the search. Used together with search_queries to focus results on the most relevant content. Should be self-contained with enough context to understand the intent of the search." }, "search_queries": { "items": { "type": "string" }, "type": "array", "title": "Search Queries", "description": "Concise keyword search queries, 3-6 words each. At least one query is required, provide 2-3 for best results. Used together with objective to focus results on the most relevant content." }, "mode": { "anyOf": [ { "type": "string", "enum": [ "turbo", "basic", "advanced" ] }, { "type": "null" } ], "title": "Mode", "description": "Search mode preset: supported values are `turbo`, `basic`, and `advanced`. Turbo mode is optimized for the fastest responses. Basic mode offers low latency and works best with 2-3 high-quality search_queries. Advanced mode provides higher quality with more advanced retrieval and compression. Defaults to `advanced` when omitted." }, "max_chars_total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Chars Total", "description": "Upper bound on total characters across excerpts from all results." }, "session_id": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Session Id", "description": "Session identifier to track calls across separate search and extract calls, to be used as part of a larger task. Specifying it may give better contextual results for subsequent API calls." }, "client_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Model", "description": "The model generating this request and consuming the results. Enables optimizations and tailors default settings for the model's capabilities.", "examples": [ "claude-opus-4-7", "gpt-5.4", "gemini-3.1-pro" ] }, "advanced_settings": { "anyOf": [ { "$ref": "#/components/schemas/AdvancedSearchSettings" }, { "type": "null" } ], "description": "Advanced configuration for source policy, fetch policy, and excerpt settings. May impact result quality and latency unless used carefully. When omitted, excerpts are enabled by default." } }, "additionalProperties": false, "type": "object", "required": [ "search_queries" ], "title": "V1SearchRequest", "description": "Search request." }, "V1SearchResponse": { "properties": { "search_id": { "type": "string", "title": "Search Id", "description": "Search ID. Example: `search_cad0a6d2dec046bd95ae900527d880e7`" }, "results": { "items": { "$ref": "#/components/schemas/V1WebSearchResult" }, "type": "array", "title": "Results", "description": "A list of search results, ordered by decreasing relevance." }, "warnings": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Warning" }, "type": "array" }, { "type": "null" } ], "title": "Warnings", "description": "Warnings for the search request, if any." }, "usage": { "anyOf": [ { "items": { "$ref": "#/components/schemas/UsageItem" }, "type": "array" }, { "type": "null" } ], "title": "Usage", "description": "Usage metrics for the search request." }, "session_id": { "type": "string", "title": "Session Id", "description": "Session identifier, echoed back from the request if provided, otherwise generated by the server. Should be passed to future search and extract calls made by the agent as part of the same larger task.", "examples": [ "session_8a911eb27c7a4afaa20d0d9dc98d07c0" ] } }, "type": "object", "required": [ "search_id", "results", "session_id" ], "title": "V1SearchResponse", "description": "Search response." }, "V1WebSearchResult": { "properties": { "url": { "type": "string", "title": "Url", "description": "URL associated with the search result." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Title", "description": "Title of the webpage, if available." }, "publish_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Publish Date", "description": "Publish date of the webpage in YYYY-MM-DD format, if available." }, "excerpts": { "items": { "type": "string" }, "type": "array", "title": "Excerpts", "description": "Relevant excerpted content from the URL, formatted as markdown." } }, "type": "object", "required": [ "url", "excerpts" ], "title": "V1WebSearchResult", "description": "A single search result from the web search API." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "Warning": { "properties": { "type": { "type": "string", "enum": [ "spec_validation_warning", "input_validation_warning", "warning" ], "title": "Type", "description": "Type of warning. Note that adding new warning types is considered a backward-compatible change.", "examples": [ "spec_validation_warning", "input_validation_warning" ] }, "message": { "type": "string", "title": "Message", "description": "Human-readable message." }, "detail": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Detail", "description": "Optional detail supporting the warning." } }, "type": "object", "required": [ "type", "message" ], "title": "Warning", "description": "Human-readable message for a task." }, "Webhook": { "properties": { "url": { "type": "string", "title": "Url", "description": "URL for the webhook." }, "event_types": { "items": { "type": "string", "enum": [ "task_run.status" ] }, "type": "array", "title": "Event Types", "description": "Event types to send the webhook notifications for.", "default": [] } }, "type": "object", "required": [ "url" ], "title": "Webhook", "description": "Webhooks for Task Runs." }, "openai__types__chat__chat_completion__Moderation": { "properties": { "input": { "anyOf": [ { "$ref": "#/components/schemas/ModerationInputModerationResults" }, { "$ref": "#/components/schemas/openai__types__chat__chat_completion__ModerationInputError" } ], "title": "Input" }, "output": { "anyOf": [ { "$ref": "#/components/schemas/ModerationOutputModerationResults" }, { "$ref": "#/components/schemas/openai__types__chat__chat_completion__ModerationOutputError" } ], "title": "Output" } }, "additionalProperties": true, "type": "object", "required": [ "input", "output" ], "title": "Moderation", "description": "Moderation results for the request input and generated output, if moderated\ncompletions were requested." }, "openai__types__chat__chat_completion__ModerationInputError": { "properties": { "code": { "type": "string", "title": "Code" }, "message": { "type": "string", "title": "Message" }, "type": { "type": "string", "const": "error", "title": "Type" } }, "additionalProperties": true, "type": "object", "required": [ "code", "message", "type" ], "title": "ModerationInputError", "description": "An error produced while attempting moderation." }, "openai__types__chat__chat_completion__ModerationOutputError": { "properties": { "code": { "type": "string", "title": "Code" }, "message": { "type": "string", "title": "Message" }, "type": { "type": "string", "const": "error", "title": "Type" } }, "additionalProperties": true, "type": "object", "required": [ "code", "message", "type" ], "title": "ModerationOutputError", "description": "An error produced while attempting moderation." }, "openai__types__shared_params__response_format_json_object__ResponseFormatJSONObject": { "properties": { "type": { "type": "string", "const": "json_object", "title": "Type" } }, "type": "object", "required": [ "type" ], "title": "ResponseFormatJSONObject", "description": "JSON object response format.\n\nAn older method of generating JSON responses.\nUsing `json_schema` is recommended for models that support it. Note that the\nmodel will not generate JSON without a system or user message instructing it\nto do so." }, "openai__types__shared_params__response_format_text__ResponseFormatText": { "properties": { "type": { "type": "string", "const": "text", "title": "Type" } }, "type": "object", "required": [ "type" ], "title": "ResponseFormatText", "description": "Default response format. Used to generate text responses." }, "ParallelBeta": { "anyOf": [ { "enum": [ "mcp-server-2025-07-17", "events-sse-2025-07-24", "webhook-2025-08-12", "findall-2025-09-15", "search-extract-2025-10-10", "field-basis-2025-11-25" ], "type": "string" }, { "type": "string" } ], "description": "Model for the parallel-beta header.", "title": "ParallelBeta" }, "ChoiceDelta": { "additionalProperties": true, "description": "A chat completion delta generated by streamed model responses.", "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Content" }, "function_call": { "anyOf": [ { "$ref": "#/components/schemas/ChoiceDeltaFunctionCall" }, { "type": "null" } ], "default": null }, "refusal": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Refusal" }, "role": { "anyOf": [ { "enum": [ "developer", "system", "user", "assistant", "tool" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Role" }, "tool_calls": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ChoiceDeltaToolCall" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Tool Calls" } }, "title": "ChoiceDelta", "type": "object" }, "ChoiceDeltaFunctionCall": { "additionalProperties": true, "description": "Deprecated and replaced by `tool_calls`.\n\nThe name and arguments of a function that should be called, as generated by the model.", "properties": { "arguments": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Arguments" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" } }, "title": "ChoiceDeltaFunctionCall", "type": "object" }, "ChoiceDeltaToolCall": { "additionalProperties": true, "properties": { "index": { "title": "Index", "type": "integer" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "function": { "anyOf": [ { "$ref": "#/components/schemas/ChoiceDeltaToolCallFunction" }, { "type": "null" } ], "default": null }, "type": { "anyOf": [ { "const": "function", "type": "string" }, { "type": "null" } ], "default": null, "title": "Type" } }, "required": [ "index" ], "title": "ChoiceDeltaToolCall", "type": "object" }, "ChoiceDeltaToolCallFunction": { "additionalProperties": true, "properties": { "arguments": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Arguments" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" } }, "title": "ChoiceDeltaToolCallFunction", "type": "object" }, "Moderation": { "additionalProperties": true, "description": "Moderation results for the response input and output, if moderated completions were requested.", "properties": { "input": { "anyOf": [ { "$ref": "#/components/schemas/ModerationInputModerationResult" }, { "$ref": "#/components/schemas/ModerationInputError" } ], "title": "Input" }, "output": { "anyOf": [ { "$ref": "#/components/schemas/ModerationOutputModerationResult" }, { "$ref": "#/components/schemas/ModerationOutputError" } ], "title": "Output" } }, "required": [ "input", "output" ], "title": "Moderation", "type": "object" }, "ModerationInputError": { "additionalProperties": true, "description": "An error produced while attempting moderation for the response input or output.", "properties": { "code": { "title": "Code", "type": "string" }, "message": { "title": "Message", "type": "string" }, "type": { "const": "error", "title": "Type", "type": "string" } }, "required": [ "code", "message", "type" ], "title": "ModerationInputError", "type": "object" }, "ModerationOutputError": { "additionalProperties": true, "description": "An error produced while attempting moderation for the response input or output.", "properties": { "code": { "title": "Code", "type": "string" }, "message": { "title": "Message", "type": "string" }, "type": { "const": "error", "title": "Type", "type": "string" } }, "required": [ "code", "message", "type" ], "title": "ModerationOutputError", "type": "object" }, "ChatCompletionResponseChunk": { "additionalProperties": true, "description": "Chat completion response chunk.", "properties": { "id": { "description": "The id of the chat completion response chunk.", "title": "Id", "type": "string" }, "choices": { "items": { "$ref": "#/components/schemas/Choice" }, "title": "Choices", "type": "array" }, "created": { "title": "Created", "type": "integer" }, "model": { "title": "Model", "type": "string" }, "object": { "const": "chat.completion.chunk", "title": "Object", "type": "string" }, "moderation": { "anyOf": [ { "$ref": "#/components/schemas/Moderation" }, { "type": "null" } ], "default": null }, "service_tier": { "anyOf": [ { "enum": [ "auto", "default", "flex", "scale", "priority" ], "type": "string" }, { "type": "null" } ], "default": null, "title": "Service Tier" }, "system_fingerprint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "System Fingerprint" }, "usage": { "anyOf": [ { "$ref": "#/components/schemas/CompletionUsage" }, { "type": "null" } ], "default": null }, "type": { "const": "chat.completion.chunk", "description": "The type of the chat completion chunk. Always `chat.completion.chunk`.", "title": "Type", "type": "string" }, "basis": { "default": [], "description": "Basis for the chat completion chunk, including citations and reasoning supporting the output.", "items": { "$ref": "#/components/schemas/FieldBasis" }, "title": "Basis", "type": "array" }, "interaction_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Identifier for this interaction. Pass as previous_interaction_id for follow-ups.", "title": "Interaction Id" } }, "required": [ "id", "choices", "created", "model", "object", "type" ], "title": "ChatCompletionResponseChunk", "type": "object" }, "AnnotationURLCitation": { "additionalProperties": true, "description": "A citation for a web resource used to generate a model response.", "properties": { "end_index": { "title": "End Index", "type": "integer" }, "start_index": { "title": "Start Index", "type": "integer" }, "title": { "title": "Title", "type": "string" }, "type": { "const": "url_citation", "title": "Type", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "end_index", "start_index", "title", "type", "url" ], "title": "AnnotationURLCitation", "type": "object" }, "ResponseCompletedEvent": { "additionalProperties": true, "properties": { "response": { "$ref": "#/components/schemas/Response" }, "sequence_number": { "title": "Sequence Number", "type": "integer" }, "type": { "const": "response.completed", "title": "Type", "type": "string" } }, "required": [ "response", "sequence_number", "type" ], "title": "ResponseCompletedEvent", "type": "object" }, "ResponseContentPartAddedEvent": { "additionalProperties": true, "properties": { "content_index": { "title": "Content Index", "type": "integer" }, "item_id": { "title": "Item Id", "type": "string" }, "output_index": { "title": "Output Index", "type": "integer" }, "part": { "$ref": "#/components/schemas/ResponseOutputText" }, "sequence_number": { "title": "Sequence Number", "type": "integer" }, "type": { "const": "response.content_part.added", "title": "Type", "type": "string" } }, "required": [ "content_index", "item_id", "output_index", "part", "sequence_number", "type" ], "title": "ResponseContentPartAddedEvent", "type": "object" }, "ResponseContentPartDoneEvent": { "additionalProperties": true, "properties": { "content_index": { "title": "Content Index", "type": "integer" }, "item_id": { "title": "Item Id", "type": "string" }, "output_index": { "title": "Output Index", "type": "integer" }, "part": { "$ref": "#/components/schemas/ResponseOutputText" }, "sequence_number": { "title": "Sequence Number", "type": "integer" }, "type": { "const": "response.content_part.done", "title": "Type", "type": "string" } }, "required": [ "content_index", "item_id", "output_index", "part", "sequence_number", "type" ], "title": "ResponseContentPartDoneEvent", "type": "object" }, "ResponseCreatedEvent": { "additionalProperties": true, "properties": { "response": { "$ref": "#/components/schemas/Response" }, "sequence_number": { "title": "Sequence Number", "type": "integer" }, "type": { "const": "response.created", "title": "Type", "type": "string" } }, "required": [ "response", "sequence_number", "type" ], "title": "ResponseCreatedEvent", "type": "object" }, "ResponseFailedEvent": { "additionalProperties": true, "properties": { "response": { "$ref": "#/components/schemas/Response" }, "sequence_number": { "title": "Sequence Number", "type": "integer" }, "type": { "const": "response.failed", "title": "Type", "type": "string" } }, "required": [ "response", "sequence_number", "type" ], "title": "ResponseFailedEvent", "type": "object" }, "ResponseInProgressEvent": { "additionalProperties": true, "properties": { "response": { "$ref": "#/components/schemas/Response" }, "sequence_number": { "title": "Sequence Number", "type": "integer" }, "type": { "const": "response.in_progress", "title": "Type", "type": "string" } }, "required": [ "response", "sequence_number", "type" ], "title": "ResponseInProgressEvent", "type": "object" }, "ResponseIncompleteEvent": { "additionalProperties": true, "properties": { "response": { "$ref": "#/components/schemas/Response" }, "sequence_number": { "title": "Sequence Number", "type": "integer" }, "type": { "const": "response.incomplete", "title": "Type", "type": "string" } }, "required": [ "response", "sequence_number", "type" ], "title": "ResponseIncompleteEvent", "type": "object" }, "ResponseOutputItemAddedEvent": { "additionalProperties": true, "properties": { "item": { "$ref": "#/components/schemas/ResponseOutputMessage" }, "output_index": { "title": "Output Index", "type": "integer" }, "sequence_number": { "title": "Sequence Number", "type": "integer" }, "type": { "const": "response.output_item.added", "title": "Type", "type": "string" } }, "required": [ "item", "output_index", "sequence_number", "type" ], "title": "ResponseOutputItemAddedEvent", "type": "object" }, "ResponseOutputItemDoneEvent": { "additionalProperties": true, "properties": { "item": { "$ref": "#/components/schemas/ResponseOutputMessage" }, "output_index": { "title": "Output Index", "type": "integer" }, "sequence_number": { "title": "Sequence Number", "type": "integer" }, "type": { "const": "response.output_item.done", "title": "Type", "type": "string" } }, "required": [ "item", "output_index", "sequence_number", "type" ], "title": "ResponseOutputItemDoneEvent", "type": "object" }, "ResponseOutputTextAnnotationAddedEvent": { "additionalProperties": true, "properties": { "annotation": { "$ref": "#/components/schemas/AnnotationURLCitation" }, "annotation_index": { "title": "Annotation Index", "type": "integer" }, "content_index": { "title": "Content Index", "type": "integer" }, "item_id": { "title": "Item Id", "type": "string" }, "output_index": { "title": "Output Index", "type": "integer" }, "sequence_number": { "title": "Sequence Number", "type": "integer" }, "type": { "const": "response.output_text.annotation.added", "title": "Type", "type": "string" } }, "required": [ "annotation", "annotation_index", "content_index", "item_id", "output_index", "sequence_number", "type" ], "title": "ResponseOutputTextAnnotationAddedEvent", "type": "object" }, "ResponseTextDeltaEvent": { "additionalProperties": true, "description": "Emitted when there is an additional text delta.", "properties": { "content_index": { "title": "Content Index", "type": "integer" }, "delta": { "title": "Delta", "type": "string" }, "item_id": { "title": "Item Id", "type": "string" }, "logprobs": { "items": { "$ref": "#/components/schemas/openai__types__responses__response_text_delta_event__Logprob" }, "title": "Logprobs", "type": "array" }, "output_index": { "title": "Output Index", "type": "integer" }, "sequence_number": { "title": "Sequence Number", "type": "integer" }, "type": { "const": "response.output_text.delta", "title": "Type", "type": "string" } }, "required": [ "content_index", "delta", "item_id", "logprobs", "output_index", "sequence_number", "type" ], "title": "ResponseTextDeltaEvent", "type": "object" }, "ResponseTextDoneEvent": { "additionalProperties": true, "description": "Emitted when text content is finalized.", "properties": { "content_index": { "title": "Content Index", "type": "integer" }, "item_id": { "title": "Item Id", "type": "string" }, "logprobs": { "items": { "$ref": "#/components/schemas/openai__types__responses__response_text_done_event__Logprob" }, "title": "Logprobs", "type": "array" }, "output_index": { "title": "Output Index", "type": "integer" }, "sequence_number": { "title": "Sequence Number", "type": "integer" }, "text": { "title": "Text", "type": "string" }, "type": { "const": "response.output_text.done", "title": "Type", "type": "string" } }, "required": [ "content_index", "item_id", "logprobs", "output_index", "sequence_number", "text", "type" ], "title": "ResponseTextDoneEvent", "type": "object" }, "openai__types__responses__response_output_text__Logprob": { "additionalProperties": true, "description": "The log probability of a token.", "properties": { "token": { "title": "Token", "type": "string" }, "bytes": { "items": { "type": "integer" }, "title": "Bytes", "type": "array" }, "logprob": { "title": "Logprob", "type": "number" }, "top_logprobs": { "items": { "$ref": "#/components/schemas/openai__types__responses__response_output_text__LogprobTopLogprob" }, "title": "Top Logprobs", "type": "array" } }, "required": [ "token", "bytes", "logprob", "top_logprobs" ], "title": "Logprob", "type": "object" }, "openai__types__responses__response_output_text__LogprobTopLogprob": { "additionalProperties": true, "description": "The top log probability of a token.", "properties": { "token": { "title": "Token", "type": "string" }, "bytes": { "items": { "type": "integer" }, "title": "Bytes", "type": "array" }, "logprob": { "title": "Logprob", "type": "number" } }, "required": [ "token", "bytes", "logprob" ], "title": "LogprobTopLogprob", "type": "object" }, "openai__types__responses__response_text_delta_event__Logprob": { "additionalProperties": true, "description": "A logprob is the logarithmic probability that the model assigns to producing\na particular token at a given position in the sequence. Less-negative (higher)\nlogprob values indicate greater model confidence in that token choice.", "properties": { "token": { "title": "Token", "type": "string" }, "logprob": { "title": "Logprob", "type": "number" }, "top_logprobs": { "anyOf": [ { "items": { "$ref": "#/components/schemas/openai__types__responses__response_text_delta_event__LogprobTopLogprob" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Top Logprobs" } }, "required": [ "token", "logprob" ], "title": "Logprob", "type": "object" }, "openai__types__responses__response_text_delta_event__LogprobTopLogprob": { "additionalProperties": true, "properties": { "token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Token" }, "logprob": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Logprob" } }, "title": "LogprobTopLogprob", "type": "object" }, "openai__types__responses__response_text_done_event__Logprob": { "additionalProperties": true, "description": "A logprob is the logarithmic probability that the model assigns to producing\na particular token at a given position in the sequence. Less-negative (higher)\nlogprob values indicate greater model confidence in that token choice.", "properties": { "token": { "title": "Token", "type": "string" }, "logprob": { "title": "Logprob", "type": "number" }, "top_logprobs": { "anyOf": [ { "items": { "$ref": "#/components/schemas/openai__types__responses__response_text_done_event__LogprobTopLogprob" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Top Logprobs" } }, "required": [ "token", "logprob" ], "title": "Logprob", "type": "object" }, "openai__types__responses__response_text_done_event__LogprobTopLogprob": { "additionalProperties": true, "properties": { "token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Token" }, "logprob": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Logprob" } }, "title": "LogprobTopLogprob", "type": "object" }, "ResponseStreamEvent": { "anyOf": [ { "$ref": "#/components/schemas/ResponseCreatedEvent" }, { "$ref": "#/components/schemas/ResponseInProgressEvent" }, { "$ref": "#/components/schemas/ResponseOutputItemAddedEvent" }, { "$ref": "#/components/schemas/ResponseContentPartAddedEvent" }, { "$ref": "#/components/schemas/ResponseTextDeltaEvent" }, { "$ref": "#/components/schemas/ResponseTextDoneEvent" }, { "$ref": "#/components/schemas/ResponseOutputTextAnnotationAddedEvent" }, { "$ref": "#/components/schemas/ResponseContentPartDoneEvent" }, { "$ref": "#/components/schemas/ResponseOutputItemDoneEvent" }, { "$ref": "#/components/schemas/ResponseCompletedEvent" }, { "$ref": "#/components/schemas/ResponseFailedEvent" }, { "$ref": "#/components/schemas/ResponseIncompleteEvent" } ], "description": "An event in the Responses API SSE stream; `type` identifies the event.", "title": "ResponseStreamEvent" } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } } }, "tags": [ { "name": "Search", "description": "Search returns ranked URLs with extended excerpts suitable for LLM consumption. Inputs are a natural-language objective and optional keyword queries. Source policies allow including or excluding specific domains and have configurable output sizes. The returned extended snippets contain dense, relevant information from relevant pages.\n- Result: ranked list with URL, title, and long text excerpts" }, { "name": "Extract", "description": "Extract returns excerpts or full content from one or more URLs. Inputs are a list of URLs and an optional search objective and keyword queries. The returned excerpts or full content is formatted as markdown and suitable for LLM consumption.\n- Result: excerpts or full content from the URL formatted as markdown" }, { "name": "Tasks", "description": "The Task API executes web research and extraction tasks. Clients submit a natural-language objective with an optional input schema; the service plans retrieval, fetches relevant URLs, and returns outputs that conform to a provided or inferred JSON schema. Supports deep research style queries and can return rich structured JSON outputs. Processors trade-off between cost, latency, and quality. Each processor supports calibrated confidences.\n- Output metadata: citations, excerpts, reasoning, and confidence per field\n\nTask Groups enable batch execution of many independent Task runs with group-level monitoring and failure handling.\n- Submit hundreds or thousands of Tasks as a single group\n- Observe group progress and receive results as they complete\n- Real-time updates via Server-Sent Events (SSE)\n- Add tasks to an existing group while it is running\n- Group-level retry and error aggregation" }, { "name": "FindAll", "description": "The FindAll API discovers and evaluates entities that match complex criteria from natural language objectives. Submit a high-level goal and the service automatically generates structured match conditions, discovers relevant candidates, and evaluates each against the criteria. Returns comprehensive results with detailed reasoning, citations, and confidence scores for each match decision. Streaming events and webhooks are supported." }, { "name": "Monitor", "description": "The Monitor API watches the web for material changes on a fixed frequency. Each monitor runs once on creation and then on its configured schedule, emitting events when meaningful changes are detected.\n- `event_stream` monitors track a search query and emit an event for each new material change.\n- `snapshot` monitors track a specific task run's output and emit an event when the output changes.\n\nResults can be polled via the events endpoint or delivered via webhooks." }, { "name": "Memory", "description": "The Memory API retrieves and manages memories created by Tasks, Monitors, and FindAll runs. Memories can be personal or isolated with a `memory_scope_key`." }, { "name": "Chat API (Beta)", "description": "The Chat API provides a programmatic chat-style text generation interface. It accepts a sequence of messages and returns model responses. Intended for assistant-like interactions and evaluation. Streaming responses are supported." }, { "name": "Responses API", "description": "An OpenAI-Responses-compatible interface for answers grounded in live web research, with URL citations. Point any Responses-API client \u2014 the OpenAI Python SDK, OpenAI TypeScript SDK, the Agents SDK, or raw HTTP \u2014 at `https://api.parallel.ai` with your Parallel API key, set `model` to `parallel`, and call `/v1/responses`.\n- `input` accepts a plain string or an array of role/content messages (canonical OpenAI shape; text content only).\n- `reasoning.effort` (`low`/`medium`/`high`) controls how much research is performed, trading response time for answer quality.\n- Multi-turn via `previous_response_id`.\n- Structured outputs via `text.format = {\"type\": \"json_schema\", \"name\": ..., \"schema\": {...}}`.\n- Streaming (`stream=true`) emits the standard OpenAI Responses SSE lifecycle: `response.created` and `response.in_progress`, then output item / content part / text delta events with URL-citation annotations, the matching `*.done` events, and a terminal `response.completed` \u2014 or `response.failed` if the request fails mid-stream." } ], "servers": [ { "url": "https://api.parallel.ai", "description": "Parallel API" } ], "security": [ { "ApiKeyAuth": [] } ] }