Skip to main content
Opik Documentation

Search documentation

Type to search this documentation.

On this pageOverview

Opik REST API

The Opik REST API is currently in beta and subject to change. If you have any questions or feedback about the APIs, please reach out on GitHub: https://github.com/comet-ml/opik.

All of the methods listed in this documentation are used by either the SDK or the UI to interact with the Opik server. As a result, the methods have been optimized for these use-cases in mind. If you are looking for a method that is not listed above, please create and issue on GitHub or raise a PR!

Opik includes two main deployment options that results in slightly different API usage:

  • Self-hosted Opik instance: You will simply need to specify the URL as http://localhost:5173/api/<endpoint_path> or similar. This is the default option for the docs.
  • Opik Cloud: You will need to specify the Opik API Key and Opik Workspace in the header. The format of the header should be:
  {
    "Comet-Workspace": "your-workspace-name",
    "authorization": "your-api-key"
  }

The full payload would therefore look like:

  curl -X GET 'https://www.comet.com/opik/api/v1/private/projects' \
  -H 'Accept: application/json' \
  -H 'Comet-Workspace: <your-workspace-name>' \
  -H 'authorization: <your-api-key>'

Do take note here that the authorization header value does not include the Bearer prefix. To switch to using the Opik Cloud in the documentation, you can click on the edit button displayed when hovering over the Base URL displayed on the right hand side of the docs.

Version
1.0.0
Base URL
https://www.comet.com/opik/api

MCP OAuth8 operations

MCP OAuth 2.1 Authorization Server resources

GETGet OAuth Authorization Server Metadata/.well-known/oauth-authorization-serverGETOAuth Authorization Endpoint/oauth/authorizePOSTSubmit Authorization Consent/oauth/authorizeGETGet Authorization Consent Context/oauth/authorize/contextPOSTOAuth Dynamic Client Registration Endpoint/oauth/registerPOSTOAuth Token Revocation Endpoint/oauth/revokePOSTOAuth Token Endpoint/oauth/tokenPOSTValidate OAuth Access Token/opik/auth-oauth

System analytics queries1 operation

Internal endpoint to run Agent Insights free-form SQL

POSTExecute Agent Insights free-form SQL/v1/internal/analytics-queries/projects/{projectId}

System usage7 operations

System usage related resource

GETGet datasets information for BI events/v1/internal/usage/bi-datasetsGETGet experiments information for BI events/v1/internal/usage/bi-experimentsGETGet spans information for BI events/v1/internal/usage/bi-spansGETGet traces information for BI events/v1/internal/usage/bi-tracesGETGet spans count on previous day for all available workspaces/v1/internal/usage/workspace-span-countsGETGet spans count on previous day grouped by workspace, project and user/v1/internal/usage/workspace-span-counts-breakdownGETGet traces count on previous day for all available workspaces/v1/internal/usage/workspace-trace-counts

Agent Configs13 operations

Agent configuration management

PATCHAdd blueprint to existing config/v1/private/agent-configs/blueprintsPOSTCreate optimizer config with initial blueprint/v1/private/agent-configs/blueprintsPOSTCreate or update environments/v1/private/agent-configs/blueprints/environmentsDELETEDelete environment/v1/private/agent-configs/blueprints/environments/{env_name}/projects/{project_id}GETRetrieve blueprint by environment/v1/private/agent-configs/blueprints/environments/{env_name}/projects/{project_id}PUTSet environment by blueprint name/v1/private/agent-configs/blueprints/environments/{env_name}/projects/{project_id}GETGet blueprint history/v1/private/agent-configs/blueprints/history/projects/{project_id}GETRetrieve latest blueprint/v1/private/agent-configs/blueprints/latest/projects/{project_id}POSTCreate blueprint from mask/v1/private/agent-configs/blueprints/projects/{project_id}/masks/{mask_id}GETRetrieve blueprint by name/v1/private/agent-configs/blueprints/projects/{project_id}/names/{name}POSTRemove configuration parameters/v1/private/agent-configs/blueprints/remove-keysGETRetrieve blueprint by ID/v1/private/agent-configs/blueprints/{blueprint_id}GETRetrieve delta by blueprint ID/v1/private/agent-configs/blueprints/{blueprint_id}/deltas

Agent Insights Jobs4 operations

Per-(workspace, project) Agent Insights report configuration

GETGet Agent Insights job/v1/private/agent-insights/jobs/{projectId}PATCHUpdate Agent Insights job/v1/private/agent-insights/jobs/{projectId}POSTCreate Agent Insights job/v1/private/agent-insights/jobs/{projectId}POSTTrigger Agent Insights job/v1/private/agent-insights/jobs/{projectId}/trigger

Agent Insights4 operations

Agent Insights report results

GETFind agent insights issues/v1/private/agent-insights/issuesPOSTStore agent insights report results/v1/private/agent-insights/issuesGETGet agent insights issue by id/v1/private/agent-insights/issues/{issue_id}PATCHUpdate agent insights issue status/v1/private/agent-insights/issues/{issue_id}

Alerts7 operations

Alert resources

GETFind alerts/v1/private/alertsPOSTCreate alert/v1/private/alertsPOSTDelete alert batch/v1/private/alerts/deleteGETGet webhook payload examples/v1/private/alerts/webhooks/examplesPOSTTest alert webhook/v1/private/alerts/webhooks/testsGETGet Alert by id/v1/private/alerts/{id}PUTUpdate alert/v1/private/alerts/{id}

Annotation Queues11 operations

Private annotation queue operations

GETFind annotation queues/v1/private/annotation-queuesPOSTCreate annotation queue/v1/private/annotation-queuesPOSTCreate annotation queue batch/v1/private/annotation-queues/batchPOSTDelete annotation queue batch/v1/private/annotation-queues/deleteGETGet annotation queue by id/v1/private/annotation-queues/{id}PATCHUpdate annotation queue/v1/private/annotation-queues/{id}POSTAdd items to annotation queue/v1/private/annotation-queues/{id}/items/addPOSTRemove items from annotation queue/v1/private/annotation-queues/{id}/items/deletePOSTSearch annotation queue items/v1/private/annotation-queues/{id}/items/searchPUTCreate or extend annotation queue item lock/v1/private/annotation-queues/{queueId}/items/{itemId}/lockGETGet all active locks for an annotation queue/v1/private/annotation-queues/{queueId}/locks

Assertion Results1 operation

Assertion result related resources

PUTBatch ingestion of assertion results/v1/private/assertion-results

Attachments6 operations

Attachments related resources

POSTDelete attachments/v1/private/attachment/deleteGETDownload attachment from MinIO/v1/private/attachment/downloadGETAttachments list for entity/v1/private/attachment/listPUTUpload attachment to MinIO/v1/private/attachment/uploadPOSTComplete multipart attachment upload/v1/private/attachment/upload-completePOSTStart multipart attachment upload/v1/private/attachment/upload-start

Check2 operations

Access check resources

POSTCheck user access to workspace/v1/private/authGETUser's default workspace name/v1/private/auth/workspace

Automation rule evaluators6 operations

Automation rule evaluators resource

GETFind project Evaluators/v1/private/automations/evaluatorsPOSTCreate automation rule evaluator/v1/private/automations/evaluatorsPOSTDelete automation rule evaluators/v1/private/automations/evaluators/deleteGETGet automation rule evaluator by id/v1/private/automations/evaluators/{id}PATCHUpdate Automation Rule Evaluator by id/v1/private/automations/evaluators/{id}GETGet automation rule evaluator logs by id/v1/private/automations/evaluators/{id}/logs

Chat Completions1 operation

Chat Completions related resources

POSTCreate chat completions/v1/private/chat/completions

Dashboards6 operations

Workspace Dashboard resources

GETFind dashboards/v1/private/dashboardsPOSTCreate dashboard/v1/private/dashboardsPOSTDelete dashboards/v1/private/dashboards/delete-batchDELETEDelete dashboard/v1/private/dashboards/{dashboardId}GETGet dashboard by id/v1/private/dashboards/{dashboardId}PATCHUpdate dashboard/v1/private/dashboards/{dashboardId}

Datasets36 operations

Dataset resources

GETFind datasets/v1/private/datasetsPOSTCreate dataset/v1/private/datasetsPOSTDelete dataset by name/v1/private/datasets/deletePOSTDelete datasets/v1/private/datasets/delete-batchGETGet all dataset export jobs/v1/private/datasets/export-jobsGETGet dataset export job status/v1/private/datasets/export-jobs/{jobId}GETDownload dataset export file/v1/private/datasets/export-jobs/{jobId}/downloadPUTMark dataset export job as viewed/v1/private/datasets/export-jobs/{jobId}/mark-viewedPUTCreate/update dataset items/v1/private/datasets/itemsPATCHBatch update dataset items/v1/private/datasets/items/batchPOSTDelete dataset items/v1/private/datasets/items/deletePOSTCreate dataset items from CSV file/v1/private/datasets/items/from-csvPOSTCreate dataset items from JSON file/v1/private/datasets/items/from-jsonPOSTStream dataset items/v1/private/datasets/items/streamGETGet dataset item by id/v1/private/datasets/items/{itemId}PATCHPartially update dataset item by id/v1/private/datasets/items/{itemId}POSTGet dataset by name/v1/private/datasets/retrievePOSTCreate dataset items from spans/v1/private/datasets/{dataset_id}/items/from-spansPOSTCreate dataset items from traces/v1/private/datasets/{dataset_id}/items/from-tracesDELETEDelete dataset by id/v1/private/datasets/{id}GETGet dataset by id/v1/private/datasets/{id}PUTUpdate dataset by id/v1/private/datasets/{id}POSTExpand dataset with synthetic samples/v1/private/datasets/{id}/expansionsPOSTStart dataset CSV export/v1/private/datasets/{id}/exportGETGet dataset items/v1/private/datasets/{id}/itemsPOSTApply changes to dataset items/v1/private/datasets/{id}/items/changesGETFind dataset items with experiment items/v1/private/datasets/{id}/items/experiments/itemsGETGet dataset items output columns/v1/private/datasets/{id}/items/experiments/items/output/columnsGETGet experiment items stats for dataset/v1/private/datasets/{id}/items/experiments/items/statsGETList dataset versions/v1/private/datasets/{id}/versionsGETCompare latest version with draft/v1/private/datasets/{id}/versions/diffPATCHUpdate dataset version/v1/private/datasets/{id}/versions/hash/{versionHash}POSTCreate version tag/v1/private/datasets/{id}/versions/hash/{versionHash}/tagsPOSTRestore dataset to a previous version/v1/private/datasets/{id}/versions/restorePOSTRetrieve dataset version by name/v1/private/datasets/{id}/versions/retrieveDELETEDelete version tag/v1/private/datasets/{id}/versions/{versionHash}/tags/{tag}

Environments5 operations

Environment related resources

GETFind environments/v1/private/environmentsPOSTCreate environment/v1/private/environmentsPOSTDelete environments/v1/private/environments/deleteGETGet environment by id/v1/private/environments/{id}PATCHUpdate environment by id/v1/private/environments/{id}

Experiments17 operations

Experiment resources

GETFind experiments/v1/private/experimentsPOSTCreate experiment/v1/private/experimentsPATCHBatch update experiments/v1/private/experiments/batchPOSTDelete experiments by id/v1/private/experiments/deletePOSTCreate and execute experiment/v1/private/experiments/executeGETFind Feedback Score names/v1/private/experiments/feedback-scores/namesPOSTFinish experiments/v1/private/experiments/finishGETFind experiment groups/v1/private/experiments/groupsGETFind experiment groups with aggregations/v1/private/experiments/groups/aggregationsPOSTCreate experiment items/v1/private/experiments/itemsPUTRecord experiment items in bulk/v1/private/experiments/items/bulkPOSTDelete experiment items/v1/private/experiments/items/deletePOSTStream experiment items/v1/private/experiments/items/streamGETGet experiment item by id/v1/private/experiments/items/{id}POSTStream experiments/v1/private/experiments/streamGETGet experiment by id/v1/private/experiments/{id}PATCHUpdate experiment by id/v1/private/experiments/{id}

Feedback-definitions6 operations

Feedback definitions related resources

GETFind Feedback definitions/v1/private/feedback-definitionsPOSTCreate feedback definition/v1/private/feedback-definitionsPOSTDelete feedback definitions/v1/private/feedback-definitions/deleteDELETEDelete feedback definition by id/v1/private/feedback-definitions/{id}GETGet feedback definition by id/v1/private/feedback-definitions/{id}PUTUpdate feedback definition by id/v1/private/feedback-definitions/{id}

Guardrails1 operation

Guardrails related resources

POSTCreate guardrails for traces in a batch/v1/private/guardrails

Insights Views6 operations

Insights View resources

GETFind insights views/v1/private/insights-viewsPOSTCreate insights view/v1/private/insights-viewsPOSTDelete insights views/v1/private/insights-views/delete-batchDELETEDelete insights view/v1/private/insights-views/{insightsViewId}GETGet insights view by id/v1/private/insights-views/{insightsViewId}PATCHUpdate insights view/v1/private/insights-views/{insightsViewId}

LLM Models1 operation

LLM model registry resources

GETGet LLM models/v1/private/llm/models

LlmProviderKey6 operations

LLM Provider Key

GETFind LLM Provider's ApiKeys/v1/private/llm-provider-keyPOSTStore LLM Provider's ApiKey/v1/private/llm-provider-keyPOSTTest a provider's dynamic token auth/v1/private/llm-provider-key/auth-config/testPOSTDelete LLM Provider's ApiKeys/v1/private/llm-provider-key/deleteGETGet LLM Provider's ApiKey by id/v1/private/llm-provider-key/{id}PATCHUpdate LLM Provider's ApiKey/v1/private/llm-provider-key/{id}

Runners18 operations

Local runner management endpoints

GETList local runners/v1/private/local-runnersPOSTCreate local runner job/v1/private/local-runners/jobsGETGet local runner job/v1/private/local-runners/jobs/{jobId}POSTCancel local runner job/v1/private/local-runners/jobs/{jobId}/cancelGETGet local runner job logs/v1/private/local-runners/jobs/{jobId}/logsPOSTAppend local runner job logs/v1/private/local-runners/jobs/{jobId}/logsPOSTReport local runner job result/v1/private/local-runners/jobs/{jobId}/resultsDELETEDisconnect local runner/v1/private/local-runners/{runnerId}GETGet local runner/v1/private/local-runners/{runnerId}PUTRegister local runner agents/v1/private/local-runners/{runnerId}/agentsPOSTSubmit bridge command/v1/private/local-runners/{runnerId}/bridge/commandsPOSTPoll next bridge commands/v1/private/local-runners/{runnerId}/bridge/commands/nextGETGet bridge command/v1/private/local-runners/{runnerId}/bridge/commands/{commandId}POSTReport bridge command result/v1/private/local-runners/{runnerId}/bridge/commands/{commandId}/resultsPATCHPatch runner checklist/v1/private/local-runners/{runnerId}/checklistPOSTLocal runner heartbeat/v1/private/local-runners/{runnerId}/heartbeatsGETList local runner jobs/v1/private/local-runners/{runnerId}/jobsPOSTNext local runner job/v1/private/local-runners/{runnerId}/jobs/next

Manual Evaluation3 operations

Manual evaluation resources for traces, threads, and spans

POSTManually evaluate spans/v1/private/manual-evaluation/spansPOSTManually evaluate threads/v1/private/manual-evaluation/threadsPOSTManually evaluate traces/v1/private/manual-evaluation/traces

Ollama2 operations

Ollama provider configuration endpoints with OpenAI-compatible API support.

POSTList available Ollama models/v1/private/ollama/modelsPOSTTest connection to Ollama instance/v1/private/ollama/test-connection

Ollie State3 operations

Ollie pod state persistence

DELETEDelete ollie state/v1/private/ollie/stateGETDownload ollie state/v1/private/ollie/statePUTReplace ollie state/v1/private/ollie/state

OpenTelemetry Ingestion1 operation

Resource to ingest Traces and Spans via OpenTelemetry

POST/v1/private/otel/v1/traces

Optimizations7 operations

Optimization resources

GETFind optimizations/v1/private/optimizationsPOSTCreate optimization/v1/private/optimizationsPUTUpsert optimization/v1/private/optimizationsPOSTDelete optimizations by id/v1/private/optimizations/deleteGETGet Studio optimization logs/v1/private/optimizations/studio/{id}/logsGETGet optimization by id/v1/private/optimizations/{id}PUTUpdate optimization by id/v1/private/optimizations/{id}

Pairing2 operations

Pairing sessions for the opik connect and opik endpoint CLI commands

POSTCreate a pairing session/v1/private/pairing/sessionsPOSTActivate a pairing session/v1/private/pairing/sessions/{sessionId}/activate

Projects19 operations

Project related resources

GETFind projects/v1/private/projectsPOSTCreate project/v1/private/projectsPOSTDelete projects/v1/private/projects/deleteGETFind Feedback Score names By Project Ids/v1/private/projects/feedback-scores/namesPOSTRetrieve project/v1/private/projects/retrieveGETGet Project Stats/v1/private/projects/statsDELETEDelete project by id/v1/private/projects/{id}GETGet project by id/v1/private/projects/{id}PATCHUpdate project by id/v1/private/projects/{id}POSTGet Project KPI Cards/v1/private/projects/{id}/kpi-cardsPOSTGet Project Metrics/v1/private/projects/{id}/metricsGETFind Token Usage names/v1/private/projects/{id}/token-usage/namesGETGet recent activity for a project/v1/private/projects/{projectId}/activitiesGETFind alerts by project/v1/private/projects/{projectId}/alertsGETFind dashboards by project/v1/private/projects/{projectId}/dashboardsGETFind datasets by project/v1/private/projects/{projectId}/datasetsGETFind experiments by project/v1/private/projects/{projectId}/experimentsGETFind optimizations by project/v1/private/projects/{projectId}/optimizationsGETGet prompts by project/v1/private/projects/{projectId}/prompts

Prompts17 operations

Prompt resources

GETGet prompts/v1/private/promptsPOSTCreate prompt/v1/private/promptsGETGet prompt by commit/v1/private/prompts/by-commit/{commit}POSTDelete prompts/v1/private/prompts/deletePOSTGet prompts by commits/v1/private/prompts/retrieve-by-commitsPATCHUpdate prompt versions/v1/private/prompts/versionsPOSTCreate prompt version/v1/private/prompts/versionsPOSTRetrieve prompt version/v1/private/prompts/versions/retrievePOSTRetrieve prompt versions by ids/v1/private/prompts/versions/retrieve-by-idsGETGet prompt version by id/v1/private/prompts/versions/{versionId}PATCHSet prompt version environment/v1/private/prompts/versions/{versionId}/environmentsDELETEDelete prompt/v1/private/prompts/{id}GETGet prompt by id/v1/private/prompts/{id}PUTUpdate prompt/v1/private/prompts/{id}GETGet prompt versions/v1/private/prompts/{id}/versionsGETGet prompt version by sequential number/v1/private/prompts/{promptId}/versions/by-number/{versionNumber}POSTRestore prompt version/v1/private/prompts/{promptId}/versions/{versionId}/restore

Report Failures2 operations

Generic failure log for reports/jobs

GETList failures for a project/v1/private/report-failuresPOSTRecord a report/job failure/v1/private/report-failures

Reports5 operations

Ollie daily report management

GETGet reports for a project/v1/private/projects/{projectId}/reportsPOSTTrigger report generation/v1/private/projects/{projectId}/reports/generateGETGet report preferences/v1/private/projects/{projectId}/reports/preferencesPUTUpdate report preferences/v1/private/projects/{projectId}/reports/preferencesPOSTComplete report generation/v1/private/projects/{projectId}/reports/{reportId}/complete

Retention Rules4 operations

Data retention rule management

GETFind retention rules/v1/private/retention/rulesPOSTCreate retention rule/v1/private/retention/rulesDELETEDeactivate retention rule/v1/private/retention/rules/{ruleId}GETGet retention rule by id/v1/private/retention/rules/{ruleId}

Service Toggles1 operation

Service Toggles resources

GETGet Service Toggles/v1/private/toggles

Spans18 operations

Span related resources

GETGet spans by project_name or project_id and optionally by trace_id and/or type/v1/private/spansPOSTCreate span/v1/private/spansPATCHBatch update spans/v1/private/spans/batchPOSTCreate spans/v1/private/spans/batchPOSTDelete span comments/v1/private/spans/comments/deletePATCHUpdate span comment by id/v1/private/spans/comments/{commentId}GETCheck whether a project has spans/v1/private/spans/existsPUTBatch feedback scoring for spans/v1/private/spans/feedback-scoresGETFind Feedback Score names/v1/private/spans/feedback-scores/namesPOSTSearch spans/v1/private/spans/searchGETGet span stats/v1/private/spans/statsDELETEDelete span by id/v1/private/spans/{id}GETGet span by id/v1/private/spans/{id}PATCHUpdate span by id/v1/private/spans/{id}POSTAdd span comment/v1/private/spans/{id}/commentsPUTAdd span feedback score/v1/private/spans/{id}/feedback-scoresPOSTDelete span feedback score/v1/private/spans/{id}/feedback-scores/deleteGETGet span comment/v1/private/spans/{spanId}/comments/{commentId}

Traces35 operations

Trace related resources

GETGet traces by project_name or project_id/v1/private/tracesPOSTCreate trace/v1/private/tracesPATCHBatch update traces/v1/private/traces/batchPOSTCreate traces/v1/private/traces/batchPOSTDelete trace comments/v1/private/traces/comments/deletePATCHUpdate trace comment by id/v1/private/traces/comments/{commentId}POSTDelete traces/v1/private/traces/deleteGETCheck whether a project has traces/v1/private/traces/existsPUTBatch feedback scoring for traces/v1/private/traces/feedback-scoresGETFind Feedback Score names/v1/private/traces/feedback-scores/namesPOSTSearch traces/v1/private/traces/searchGETGet trace stats/v1/private/traces/statsGETGet trace threads/v1/private/traces/threadsPATCHBatch update threads/v1/private/traces/threads/batchPUTClose trace thread(s)/v1/private/traces/threads/closePOSTDelete thread comments/v1/private/traces/threads/comments/deletePATCHUpdate thread comment by id/v1/private/traces/threads/comments/{commentId}POSTDelete trace threads/v1/private/traces/threads/deletePUTBatch feedback scoring for threads/v1/private/traces/threads/feedback-scoresPOSTDelete thread feedback scores/v1/private/traces/threads/feedback-scores/deleteGETFind Trace Threads Feedback Score names/v1/private/traces/threads/feedback-scores/namesPUTOpen trace thread/v1/private/traces/threads/openPOSTGet trace thread/v1/private/traces/threads/retrievePOSTSearch trace threads/v1/private/traces/threads/searchGETGet trace thread stats/v1/private/traces/threads/statsPOSTAdd thread comment/v1/private/traces/threads/{id}/commentsGETGet thread comment/v1/private/traces/threads/{threadId}/comments/{commentId}PATCHUpdate thread/v1/private/traces/threads/{threadModelId}DELETEDelete trace by id/v1/private/traces/{id}GETGet trace by id/v1/private/traces/{id}PATCHUpdate trace by id/v1/private/traces/{id}POSTAdd trace comment/v1/private/traces/{id}/commentsPUTAdd trace feedback score/v1/private/traces/{id}/feedback-scoresPOSTDelete trace feedback score/v1/private/traces/{id}/feedback-scores/deleteGETGet trace comment/v1/private/traces/{traceId}/comments/{commentId}

Welcome Wizard2 operations

Welcome wizard tracking resources

GETGet welcome wizard tracking status/v1/private/welcome-wizardPOSTSubmit welcome wizard/v1/private/welcome-wizard

Workspace permissions1 operation

Workspace permissions related resources

GETGet workspace permissions for the authenticated user/v1/private/workspace-permissions

Workspaces9 operations

Workspace related resources

DELETEDelete workspace configuration/v1/private/workspaces/configurationsGETGet workspace configuration/v1/private/workspaces/configurationsPUTUpsert workspace configuration/v1/private/workspaces/configurationsPOSTGet cost daily data/v1/private/workspaces/costsPOSTGet costs summary/v1/private/workspaces/costs/summariesPOSTGet metric daily data/v1/private/workspaces/metricsPOSTGet workspace span metric/v1/private/workspaces/metrics/spansPOSTGet metrics summary/v1/private/workspaces/metrics/summariesPOSTGet workspace token usage names/v1/private/workspaces/token-usage/names

Redirect4 operations

Redirects for SDK generated links

GETCreate dataset redirect url/v1/session/redirect/datasetsGETCreate experiment redirect url/v1/session/redirect/experimentsGETCreate optimization redirect url/v1/session/redirect/optimizationsGETCreate project redirect url/v1/session/redirect/projects

Operations2 operations

GET/is-alive/pingGET/is-alive/ver
Documentation menu