API reference

Traces

Research and evidence: research runs, web search with evidence, and usage events.

Operations: 6
Base path: https://os.one.ml/api/v1/traces
Scopes: traces:read traces:write
API keys: 6 tested with an API key
SDK: genesis.call('traces_listRuns', …) · helpers under genesis.traces
CLI: genesis traces
MCP: 6 tools

Operations

Operation	Endpoint	API key
List runs in the verified organization	GET`/runs`	Tested with an API key
Create a research run	POST`/runs`	Tested with an API key
Read one run	GET`/runs/{id}`	Tested with an API key
Evidence collected by a run	GET`/runs/{id}/evidence`	Tested with an API key
Web search with evidence (metered as traces.search.results)	POST`/search`	Tested with an API key
Persisted Traces usage events for the verified organization	GET`/usage/events`	Tested with an API key

Runs

List runs in the verified organization

GET/v1/traces/runs

traces:readTested with an API keytraces_listRuns

Parameters

limitquery · integer

Responses

200Runs
Response fields
A JSON object.
401Verified One account identity required
403Traces permission required
404Not found in the verified organization
503Traces unavailable
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/traces/runs" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('traces_listRuns')

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "traces_listRuns",
    "arguments": {}
  }
}

Create a research run

POST/v1/traces/runs

traces:writeTested with an API keyIdempotency-Key requiredtraces_createRun

Parameters

Idempotency-Keyheader · stringrequired
Stable key; replays return the original result and are metered once

Request body application/json

typestringrequired
Run type, for example deep_research
querystring
max length 4000
categorystring
configobject

Responses

200Run accepted
Response fields
A JSON object.
201Run created
Response fields
A JSON object.
202Run accepted
Response fields
A JSON object.
401Verified One account identity required
403Traces permission required
404Not found in the verified organization
503Traces unavailable
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/traces/runs" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "string"
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const idempotencyKey = '<a stable key per change>'
const result = await genesis.call('traces_createRun', {
  body: {
    type: 'string',
  },
}, {
  headers: { 'Idempotency-Key': idempotencyKey }, // one key per change, reused on every retry
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "traces_createRun",
    "arguments": {
      "body": {
        "type": "string"
      },
      "idempotency_key": "<a stable key per change>"
    }
  }
}

Read one run

GET/v1/traces/runs/{id}

traces:readTested with an API keytraces_getRun

Parameters

idpath · stringrequired

Responses

200Run
Response fields
A JSON object.
401Verified One account identity required
403Traces permission required
404Not found in the verified organization
503Traces unavailable
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/traces/runs/$ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('traces_getRun', {
  id: '<id>',
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "traces_getRun",
    "arguments": {
      "id": "<id>"
    }
  }
}

Evidence

Evidence collected by a run

GET/v1/traces/runs/{id}/evidence

traces:readTested with an API keytraces_getRunEvidence

Parameters

idpath · stringrequired

Responses

200Run evidence
Response fields
A JSON object.
401Verified One account identity required
403Traces permission required
404Not found in the verified organization
503Traces unavailable
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/traces/runs/$ID/evidence" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('traces_getRunEvidence', {
  id: '<id>',
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "traces_getRunEvidence",
    "arguments": {
      "id": "<id>"
    }
  }
}

Search

Web search with evidence (metered as traces.search.results)

POST/v1/traces/search

traces:writeTested with an API keyIdempotency-Key requiredtraces_search

Parameters

Idempotency-Keyheader · stringrequired
Stable key; replays return the original result and are metered once

Request body application/json

querystringrequired
min length 1 · max length 2000
max_resultsinteger
min 1 · max 20

Responses

200Search results
Response fields
A JSON object.
401Verified One account identity required
403Traces permission required
404Not found in the verified organization
503Traces unavailable
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/traces/search" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "string"
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const idempotencyKey = '<a stable key per change>'
const result = await genesis.call('traces_search', {
  body: {
    query: 'string',
  },
}, {
  headers: { 'Idempotency-Key': idempotencyKey }, // one key per change, reused on every retry
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "traces_search",
    "arguments": {
      "body": {
        "query": "string"
      },
      "idempotency_key": "<a stable key per change>"
    }
  }
}

Usage

Persisted Traces usage events for the verified organization

GET/v1/traces/usage/events

traces:readTested with an API keytraces_listUsageEvents

Responses

200Usage events
Response fields
A JSON object.
401Verified One account identity required
403Traces permission required
404Not found in the verified organization
503Traces unavailable
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/traces/usage/events" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('traces_listUsageEvents')

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "traces_listUsageEvents",
    "arguments": {}
  }
}

One Superintelligence, Inc. · Built from Genesis 0.1.12 and the live gateway on 2026-10-20. Support