Projects

A project is a named group of Agent Observability data. Use one project for each application, or one for each test setup, so that the data of one stays apart from the others.

What a project holds

Data	How it belongs to a project
Datasets	Created in the project
Experiments	Created in the project
Traces	The trace carries the project name in the oodle.project attribute
Experiment rows and their scores	Through their experiment

These items are shared by all projects of the instance: prompts, evaluators and their templates, LLM connections, and webhooks. To make an evaluator score only one project, see Evaluators and projects.

The default project

Each instance has a built-in project with the name default:

• A trace without an oodle.project attribute belongs to the default project. Traffic that you sent before you used projects is in it.
• An API call that does not name a project uses the default project.
• You cannot rename or delete the default project, and you cannot create another project with the name default.

Create a project

Send POST projects to the Oodle API. Create is idempotent by name: when a project with that name exists, Oodle returns it (status 200) and does not make a second one. A new project returns status 201.

curl -X POST \
  "https://<API_DOMAIN>/v1/api/instance/<OODLE_INSTANCE>/langfuse/api/public/projects" \
  -H "X-API-KEY: $OODLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "support-agent-evals", "description": "CI evals of the support agent"}'

The reply holds the project id. Pass it as the projectId query parameter to the dataset and experiment routes. On the URL path, use default for the default project.

Method and path	Purpose
GET projects	List the projects. The default project is first, with isDefault: true
POST projects	Create a project. Body: name, optional description
GET projects/{projectId}	Get one project
PATCH projects/{projectId}	Change the description
DELETE projects/{projectId}	Delete the project and its data

The paths are under /v1/api/instance/<OODLE_INSTANCE>/langfuse/api/public/.

A project name does not change after you create it, because traces carry the name.

The Braintrust SDK also creates projects. For example, braintrust.init(project="support-agent-evals") makes the project when it does not exist. See Migrate from Braintrust.

Send traces to a project

A trace belongs to a project when its spans carry the project name in the oodle.project resource or span attribute. Set it in one of these ways.

Resource attribute

Set the attribute on the OpenTelemetry resource. This works for all SDKs and for an OpenTelemetry Collector, because the attribute is part of the data:

export OTEL_RESOURCE_ATTRIBUTES="oodle.project=support-agent-evals"

Or in code (Python):

from opentelemetry.sdk.resources import Resource

resource = Resource.create({
    "service.name": "support-agent",
    "oodle.project": "support-agent-evals",
})

Request header

Send the X-Oodle-Project header with each OTLP export. Oodle adds oodle.project to each span of the request that does not set it:

export OTEL_EXPORTER_OTLP_HEADERS="X-API-KEY=<OODLE_API_KEY>,X-OODLE-INSTANCE=<OODLE_INSTANCE>,X-Oodle-Project=support-agent-evals"

Use the header when you export directly to Oodle. An OpenTelemetry Collector does not forward the headers of your application, so with a collector, set the resource attribute, or add the header to the collector's exporter.

The Langfuse SDK sends its spans through the OpenTelemetry tracer provider of your application, so the two ways above also apply to it. See the Langfuse integration.

A span or resource that already sets oodle.project keeps its value. The header does not replace it.

Experiment traces

The traces of an experiment row also carry the experiment id in oodle.experiment.id. Set it with the X-Oodle-Experiment-Id header, or as a resource attribute. The Braintrust SDK and the Experiments API set both attributes for you.

Projects in the Agent Observability views

The project switcher at the top of the Datasets and Experiments pages selects the project that they show. The default project is selected first. The selection is in the page URL as project=<project name>, so a link that you share opens the same project, for example /genai/experiments?project=support-agent-evals.

The traces, sessions and Agent Graph pages show the default project only, so the traces of experiments in other projects stay out of them. Open an experiment row to see its trace.

The Projects page (/genai/projects) lists the projects. An Editor or an Admin can create a project there, change its description and delete it.

The Experiments page (/genai/experiments) lists the experiments of the selected project with the average of each score and a score trend. Open an experiment to see its summary against its base experiment and its rows, each with a link to its trace. Select two to five experiments and click Compare to see the rows side by side.

Evaluators and projects

Evaluators are shared by all projects. A live evaluator scores the spans that its filters match, so it scores traces of every project unless a filter limits it.

To score one project only, add a filter on the resource::oodle.project label to the evaluator, with the project name as the value. To keep an evaluator on the default project only, filter on the value default or on an empty value.

In an experiment, the evaluators that you select score the rows of that experiment, whatever their filters.

Delete a project

curl -X DELETE \
  "https://<API_DOMAIN>/v1/api/instance/<OODLE_INSTANCE>/langfuse/api/public/projects/<PROJECT_ID>" \
  -H "X-API-KEY: $OODLE_API_KEY"

Deleting a project also deletes its datasets, experiments, experiment rows and the scores of those rows. You cannot undo a delete. The traces of the project stay in the trace store until their retention ends.