API Reference

The Orq REST API lets you ingest traces, query eval scores, trigger gate evaluations, and manage projects programmatically. All endpoints are under https://api.getorqai.com/v1.

Authentication

Send your project API key as a Bearer token in the Authorization header.

Authorization: Bearer orq_live_xxxxxxxxxxxxxxxx

Ingest a trace

POST a trace payload to ingest it manually. In most cases you will use the SDK, which handles ingestion automatically. The direct API is useful for custom integrations.

import requests

payload = {
    "name": "answer-question",
    "spans": [
        {
            "name": "gpt-4o",
            "type": "llm",
            "latency_ms": 1240,
            "input_tokens": 87,
            "output_tokens": 42,
            "input": "What is the capital of the Netherlands?",
            "output": "Amsterdam is the capital city of the Netherlands."
        }
    ]
}

resp = requests.post(
    "https://api.getorqai.com/v1/traces",
    json=payload,
    headers={"Authorization": "Bearer orq_live_xxxxxxxxxxxxxxxx"},
)
print(resp.json())

const payload = {
  name: "answer-question",
  spans: [
    {
      name: "gpt-4o",
      type: "llm",
      latency_ms: 1240,
      input_tokens: 87,
      output_tokens: 42,
      input: "What is the capital of the Netherlands?",
      output: "Amsterdam is the capital city of the Netherlands.",
    },
  ],
};

const resp = await fetch("https://api.getorqai.com/v1/traces", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer orq_live_xxxxxxxxxxxxxxxx",
  },
  body: JSON.stringify(payload),
});
console.log(await resp.json());

curl -X POST https://api.getorqai.com/v1/traces \
  -H "Authorization: Bearer orq_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "answer-question",
    "spans": [{
      "name": "gpt-4o",
      "type": "llm",
      "latency_ms": 1240,
      "input_tokens": 87,
      "output_tokens": 42,
      "input": "What is the capital of the Netherlands?",
      "output": "Amsterdam is the capital city of the Netherlands."
    }]
  }'

Get eval scores for a trace

Retrieve the eval scores Orq computed for a given trace ID. Scores are available once the eval pipeline has run, typically within a few seconds of ingestion.

import requests

trace_id = "tr_0192c8a6e4f0"

resp = requests.get(
    f"https://api.getorqai.com/v1/traces/{trace_id}/scores",
    headers={"Authorization": "Bearer orq_live_xxxxxxxxxxxxxxxx"},
)
scores = resp.json()
for metric in scores["metrics"]:
    print(metric["name"], metric["score"])

const traceId = "tr_0192c8a6e4f0";

const resp = await fetch(
  `https://api.getorqai.com/v1/traces/${traceId}/scores`,
  {
    headers: { Authorization: "Bearer orq_live_xxxxxxxxxxxxxxxx" },
  }
);
const scores = await resp.json();
for (const metric of scores.metrics) {
  console.log(metric.name, metric.score);
}

curl https://api.getorqai.com/v1/traces/tr_0192c8a6e4f0/scores \
  -H "Authorization: Bearer orq_live_xxxxxxxxxxxxxxxx"

Trigger a gate evaluation

Trigger an on-demand gate check for a specific commit SHA. Returns pass or blocked with the metrics that caused the block.

import requests

resp = requests.post(
    "https://api.getorqai.com/v1/gates/evaluate",
    json={
        "project_id": "proj_08f3a1b2c9",
        "commit_sha": "a3c7f2e",
        "branch": "main",
    },
    headers={"Authorization": "Bearer orq_live_xxxxxxxxxxxxxxxx"},
)
result = resp.json()
print(result["verdict"], result.get("blocked_metrics", []))

const resp = await fetch("https://api.getorqai.com/v1/gates/evaluate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer orq_live_xxxxxxxxxxxxxxxx",
  },
  body: JSON.stringify({
    project_id: "proj_08f3a1b2c9",
    commit_sha: "a3c7f2e",
    branch: "main",
  }),
});
const result = await resp.json();
console.log(result.verdict, result.blocked_metrics ?? []);

curl -X POST https://api.getorqai.com/v1/gates/evaluate \
  -H "Authorization: Bearer orq_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_08f3a1b2c9",
    "commit_sha": "a3c7f2e",
    "branch": "main"
  }'

Rate limits

The API is rate limited per project. Free plan: 100 requests per minute. Pro plan: 2,000 requests per minute. Scale plan: custom.

Responses include X-RateLimit-Remaining and X-RateLimit-Reset headers. On 429, wait until the reset timestamp before retrying.

Need more?

The full OpenAPI spec is available at https://api.getorqai.com/v1/openapi.json. For questions or to report API issues, write to [email protected].