> ## Documentation Index > Fetch the complete documentation index at: https://docs.sidenet.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run experiment > Runs a dataset experiment against an agent. Send `agentId` (agent id or agent version id), `datasetId`, and optional `scorers` (scorer types from the catalog, e.g. "tone", "bias" — code scorers and LLM judges both supported). Set `async: true` for fire-and-forget (returns an experimentId to poll GET /api/datasets/{datasetId}/experiments/{experimentId}); omit it to block and receive the full summary. Requires X-User-Id. Each dataset item runs in its own conversation thread by default, so items never share memory state and can run concurrently. To pin an item to a specific thread (e.g. several items forming one conversation), set `requestContext.threadId` on that dataset item — and run with maxConcurrency: 1 if multiple items share a thread. Send `variables` to fill the {{placeholders}} in the agent's prompt blocks for every item; a dataset item's own `requestContext.variables` are merged over them leaf by leaf, so a row overrides only what it varies. By default the run is REFUSED (400) when a placeholder with no `|| 'default'` has no value — pass `strictVariables: false` to run anyway. The response always carries a `variables` report (supplied, required, missing, dropped, unused). ## OpenAPI ````yaml /api-reference/openapi.json post /v1/experiments openapi: 3.1.0 info: title: Sidenet API version: 1.0.0 description: >- Sidenet HTTP endpoints exposed by the Sidenet Studio. All routes require an api key that can be generated through the studio in studio.sidenet.ai. servers: - url: https://api.sidenet.ai security: - bearerAuth: [] paths: /v1/experiments: post: tags: - Experiments summary: Run experiment description: >- Runs a dataset experiment against an agent. Send `agentId` (agent id or agent version id), `datasetId`, and optional `scorers` (scorer types from the catalog, e.g. "tone", "bias" — code scorers and LLM judges both supported). Set `async: true` for fire-and-forget (returns an experimentId to poll GET /api/datasets/{datasetId}/experiments/{experimentId}); omit it to block and receive the full summary. Requires X-User-Id. Each dataset item runs in its own conversation thread by default, so items never share memory state and can run concurrently. To pin an item to a specific thread (e.g. several items forming one conversation), set `requestContext.threadId` on that dataset item — and run with maxConcurrency: 1 if multiple items share a thread. Send `variables` to fill the {{placeholders}} in the agent's prompt blocks for every item; a dataset item's own `requestContext.variables` are merged over them leaf by leaf, so a row overrides only what it varies. By default the run is REFUSED (400) when a placeholder with no `|| 'default'` has no value — pass `strictVariables: false` to run anyway. The response always carries a `variables` report (supplied, required, missing, dropped, unused). parameters: - name: X-User-Id in: header required: true description: >- User id. May also be sent in the request body or as a userId query param. schema: type: string requestBody: required: true content: application/json: schema: type: object required: - agentId - datasetId properties: agentId: type: string example: 6f1c0f4e-2b7a-4a51-9a2f-0c9d1b3e5a10 datasetId: type: string example: ds_orders_v3 scorers: description: >- Scorer types from the catalog (e.g. "tone", "bias"). Code scorers and LLM judges both supported. type: array items: type: string example: - completeness - tone async: type: boolean default: false name: type: string example: Refund tone — August description: type: string example: Checks the refund answers after the new brand-voice block metadata: type: object example: ticket: ENG-412 version: type: integer description: Dataset version to run against. Defaults to the newest. example: 3 maxConcurrency: type: integer example: 5 itemTimeout: type: integer description: Milliseconds one item may take before it is failed. example: 60000 maxRetries: type: integer default: 2 description: >- Retries per dataset item before it is recorded as failed. Defaults to 2 so a transient provider fault does not fail an item; pass 0 to fail on the first error. variables: type: object additionalProperties: true description: >- Values for the {{variable}} placeholders in the agent's prompt blocks, applied to every item. Scalars or arrays of them; a dot path up to 3 segments may be sent nested (`{ "user": { "language": "FR" } }`) or dotted (`{ "user.language": "FR" }`). Reserved: `now.*`. A dataset item's own `requestContext.variables` are merged over these leaf by leaf. Display-only — never used for authorization or identity. example: locale: English instance: store_count: 12 strictVariables: type: boolean default: true description: >- Refuse to start (400) when a placeholder with no default has no value for some item, or a supplied value is rejected by the limits. Pass false to run anyway and read the `variables` report on the response. responses: '200': description: >- The finished run, or — with `async: true` — the id of the run that was started content: application/json: schema: type: object properties: status: type: string enum: - completed - started description: '`started` on an async run; the scores are not ready yet.' experimentId: type: string description: Async runs only — poll the experiment by this id. summary: type: object description: >- Sync runs only: the scorer results over the dataset. Its shape follows the scorers you asked for. variables: type: object properties: supplied: type: array description: Variable paths you sent. items: type: string required: type: array description: Paths the agent's prompt blocks consume. items: type: string missing: type: array description: >- Required paths with no value — each renders as a literal `{{placeholder}}` in the system prompt of every affected item. items: type: string dropped: type: array description: Values rejected by the size/type limits. items: type: string unused: type: array description: Paths you sent that no block reads — usually a typo. items: type: string itemsAffected: type: integer description: >- Dataset items with a missing variable. Present only when non-zero. items: type: array description: >- Which items those are. Present only when `itemsAffected` is. items: type: object example: status: started experimentId: exp_7f31a9c2 variables: supplied: - locale required: - locale - instance.store_count missing: - instance.store_count dropped: [] unused: [] '400': description: Invalid request body or unknown scorer type '404': description: Agent or dataset not found '422': description: LLM judge could not be provisioned for this org '500': description: Agent build or experiment execution failed components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- Organization API key, generated in studio.sidenet.ai. Backend only — never in a browser. ````