{"openapi":"3.1.0","info":{"title":"LangWatch (BYOK) API","version":"0.1.0","description":"LangWatch (BYOK) lets an AI assistant read your own LangWatch data through the LangWatch API with a key you supply (LangWatch project API key). Read-only: 11 tools (search_traces, get_trace, list_datasets, list_dataset_entries, list_experiments, list_experiment_runs, list_annotations, list_simulation_runs, list_monitors, list_evaluators, list_prompts). The BYOK key travels with each request, is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-langwatch.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-langwatch/docs"},"termsOfService":"https://connectorbay.com/byok-langwatch/terms"},"servers":[{"url":"https://byok-langwatch.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-langwatch/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/search_traces":{"post":{"operationId":"search_traces","summary":"Search traces of the project in a time window by free text and/or a LangWatch filter such as status:error or has:annotat","description":"Search traces of the project in a time window by free text and/or a LangWatch filter such as status:error or has:annotation; page with scroll_id. Use for \"Which LangWatch traces had errors in the last day\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"description":"Start of the window, ISO 8601, for example 2026-10-15T00:00:00Z.","maxLength":40,"title":"Start Date","type":"string"},"end_date":{"description":"End of the window, ISO 8601, for example 2026-10-16T00:00:00Z.","maxLength":40,"title":"End Date","type":"string"},"query":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Free text to look for in trace content.","title":"Query"},"filter":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"LangWatch filter expression, for example 'status:error', 'evaluatorVerdict:fail' or 'has:feedback'.","title":"Filter"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many traces to return (1 to 100).","title":"Page Size"},"scroll_id":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"The scrollId from a previous answer to fetch the next page.","title":"Scroll Id"}},"required":["start_date","end_date"],"title":"search_tracesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_trace":{"post":{"operationId":"get_trace","summary":"Get one trace by its id (or a unique prefix of at least 8 characters) as an AI-readable digest or full JSON. Use for \"Sh","description":"Get one trace by its id (or a unique prefix of at least 8 characters) as an AI-readable digest or full JSON. Use for \"Show LangWatch trace trace_abc in digest form\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"trace_id":{"description":"Trace id, the full 32-character id or a unique prefix of at least 8 characters.","maxLength":200,"title":"Trace Id","type":"string"},"format":{"anyOf":[{"enum":["digest","json"],"type":"string"},{"type":"null"}],"default":"digest","description":"Output format: digest (compact, readable) or json (full data).","title":"Format"}},"required":["trace_id"],"title":"get_traceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_datasets":{"post":{"operationId":"list_datasets","summary":"List the project's non-archived datasets with column types and record counts. Use for \"Which datasets do I have in LangW","description":"List the project's non-archived datasets with column types and record counts. Use for \"Which datasets do I have in LangWatch\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many datasets per page (1 to 1000).","title":"Limit"}},"title":"list_datasetsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_dataset_entries":{"post":{"operationId":"list_dataset_entries","summary":"List the rows of one dataset (by slug) with paging. Use for \"Show the first rows of the LangWatch dataset 'qa-set'\".","description":"List the rows of one dataset (by slug) with paging. Use for \"Show the first rows of the LangWatch dataset 'qa-set'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dataset_slug":{"description":"Dataset slug from list_datasets.","maxLength":200,"title":"Dataset Slug","type":"string"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many rows per page (1 to 1000).","title":"Limit"}},"required":["dataset_slug"],"title":"list_dataset_entriesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_experiments":{"post":{"operationId":"list_experiments","summary":"List experiments of the project with type, run count and last run time. Use for \"Which LangWatch experiments have I run\"","description":"List experiments of the project with type, run count and last run time. Use for \"Which LangWatch experiments have I run\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many experiments per page (1 to 200).","title":"Page Size"}},"title":"list_experimentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_experiment_runs":{"post":{"operationId":"list_experiment_runs","summary":"List the runs of one experiment (by slug) with timestamps, progress and cost and duration summaries. Use for \"How did th","description":"List the runs of one experiment (by slug) with timestamps, progress and cost and duration summaries. Use for \"How did the runs of LangWatch experiment 'prompt-v2' go\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"experiment_slug":{"description":"Slug of the experiment, from list_experiments.","maxLength":200,"title":"Experiment Slug","type":"string"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many runs per page (1 to 200).","title":"Page Size"}},"required":["experiment_slug"],"title":"list_experiment_runsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_annotations":{"post":{"operationId":"list_annotations","summary":"List human annotations (comments, thumbs and expected outputs) on traces of the project. Use for \"Which traces have anno","description":"List human annotations (comments, thumbs and expected outputs) on traces of the project. Use for \"Which traces have annotations in LangWatch\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"anchor":{"anyOf":[{"enum":["trace","all"],"type":"string"},{"type":"null"}],"default":"all","description":"Which annotations: trace (trace-level only) or all.","title":"Anchor"}},"title":"list_annotationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_simulation_runs":{"post":{"operationId":"list_simulation_runs","summary":"List agent simulation runs with status, cost, duration and the first messages of each conversation. Use for \"Show recent","description":"List agent simulation runs with status, cost, duration and the first messages of each conversation. Use for \"Show recent LangWatch simulation runs\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"scenario_set_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only runs of this scenario set id.","title":"Scenario Set Id"},"batch_run_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only runs of this batch run id.","title":"Batch Run Id"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many runs to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"The nextCursor of a previous answer for the next page.","title":"Cursor"}},"title":"list_simulation_runsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_monitors":{"post":{"operationId":"list_monitors","summary":"List the online evaluation monitors configured for the project. Use for \"Which online evaluation monitors run in LangWat","description":"List the online evaluation monitors configured for the project. Use for \"Which online evaluation monitors run in LangWatch\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_monitorsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_evaluators":{"post":{"operationId":"list_evaluators","summary":"List the evaluators configured for the project. Use for \"Which evaluators are set up in LangWatch\".","description":"List the evaluators configured for the project. Use for \"Which evaluators are set up in LangWatch\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_evaluatorsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_prompts":{"post":{"operationId":"list_prompts","summary":"List the prompts managed in the project. Use for \"Which prompts are managed in LangWatch\".","description":"List the prompts managed in the project. Use for \"Which prompts are managed in LangWatch\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_promptsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}