Integration guide for agent marketplace partners

SuperOrgs is the system of record for enterprise AI agents. CEOs, CFOs, CHROs, and AI operations leaders use it to manage their whole workforce, people and agents, in one place: the agents built on your platform alongside the agents bought from other vendors. It gives them cost visibility, agent activity, agent resource planning, and reporting structures for people and agents. There is a clickable demo if you want to see it.

This is the guide we hand to agent marketplace partners. It covers how the integration works, the two ways to send runs, the activity schema, how to report cost, what is stored, what is not supported today, and how a listing works.

Why integrate with SuperOrgs

By sending cost and activity data to SuperOrgs, your platform becomes:

• More valuable in enterprise procurement. Buyers ask for one view of every agent's cost and activity, and a SuperOrgs integration answers that requirement.
• Stickier for end users. Cost transparency and activity streams reduce churn risk and increase agent adoption.
• Discoverable to the SuperOrgs install base. Your agents are listed in our Agent Marketplace.

How the integration works

Each shared customer connects your agent in SuperOrgs and mints a credential for it, so every run lands in that customer's workspace, on that agent.

1. The customer, in SuperOrgs, mints a credential for one agent under Connectors, SuperOrgs SDK, then enters it in your platform.
2. Your platform keeps one credential per customer agent and uses it for every run of that agent.
3. Your agent runtime sends each run to SuperOrgs, either as OpenTelemetry traces or through the Events API, with Authorization: Bearer sot_....
4. SuperOrgs sets the organization and agent from the credential, then stores the run with its timeline, activity, and cost.

What the customer does. In SuperOrgs they open Connectors, choose SuperOrgs SDK, then Connect an agent. They pick the agent your runtime reports as and click Mint credential. They repeat this for each of your agents they run. If your agent is not in their workspace yet, they add it first, from its Agent Marketplace listing or by hand.

What you store. The credential starts with sot_ and is shown to the customer once. Store it against that customer's agent, and send it with every request you make for that agent. A customer running five of your agents gives you five credentials.

Choose how to send

There are two ways to send runs. Both use the same credential and land in the same place.

OpenTelemetry traces. Use this path when your runtime already exports OpenTelemetry traces for each customer agent. The work on your side is pointing your trace exporter at POST https://app.superorgs.com/api/otel/v1/traces. SuperOrgs records runs, model calls, tool calls, token cost, and failures. Prompt and tool content is discarded on receipt and never stored.

The Events API. Use this path when you do not use OpenTelemetry, or when you want to send summaries, progress lines, artifacts, and handoffs. The work on your side is sending events from your runtime, directly or with the Node SDK, to POST https://app.superorgs.com/api/agent-stream/v0/events. SuperOrgs records everything in the activity schema below, including run summaries, progress lines, artifacts, and handoffs. Prompt and tool content is stored as you send it.

Both paths allow 240 requests per minute per credential.

Use one path per agent. The two paths identify runs differently, so the same work sent through both is counted twice. The customer's connection page warns when an agent has reported through both in the last 24 hours.

Send OpenTelemetry traces

If your runtime is instrumented with OpenTelemetry, point its trace exporter at SuperOrgs. No SuperOrgs package is involved.

• Endpoint: POST https://app.superorgs.com/api/otel/v1/traces
• Authentication: the customer's sot_ credential as a bearer header.
• Protocol: OTLP over HTTP, protobuf or JSON, gzip compressed or not. gRPC is not served.
• Size: keep each compressed request under 4.5 MB. After decompression a request may hold at most 8 MB and 2,048 spans.
• Rate limit: 240 requests per minute per credential. Past that the endpoint answers 429 with a Retry-After header.

Exporter configuration

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://app.superorgs.com/api/otel/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Bearer%20sot_...
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_TRACES_COMPRESSION=gzip

An OpenTelemetry Collector ignores these variables. Add an OTLP/HTTP exporter to its configuration instead:

exporters:
  otlphttp/superorgs:
    endpoint: https://app.superorgs.com/api/otel
    compression: gzip
    headers:
      authorization: "Bearer sot_..."
processors:
  batch/superorgs:
    send_batch_max_size: 2048
service:
  pipelines:
    traces/superorgs:
      receivers: [otlp]
      processors: [batch/superorgs]
      exporters: [otlphttp/superorgs]

One credential per agent's traces. Every span sent with a credential is recorded under that credential's agent, whatever the span's own attributes say. If one process or Collector serves several customers or agents, route each agent's spans to its own exporter and credential.

How spans become runs

• A trace becomes one run.
• The trace's root span, or its outermost agent span, gives the run's start, end, and outcome.
• Model-call spans (chat, text_completion, generate_content, embeddings) with token usage become token cost, priced by SuperOrgs and marked as an estimate.
• Tool spans (execute_tool) become a tool call and its result, with duration.
• A span with status ERROR becomes a failure, recorded by its error type and HTTP status, never its message.
• Any other span is dropped, and counted in the response.

SuperOrgs reads the OpenTelemetry GenAI semantic conventions (gen_ai.*). It also recognizes OpenLLMetry (Traceloop), Vercel AI SDK telemetry, and OpenInference model-call spans.

• Wrap each unit of work in an agent span (gen_ai.operation.name = invoke_agent). Without one, every model call becomes its own run.
• Export the root span. A run whose root span never arrives, for example because the process crashed, stays running.
• Resending is safe. Spans are recognized by their trace and span ids, so a resent batch is not stored twice.
• Content is not stored. Prompts, completions, tool arguments, tool results, and error messages are discarded on receipt. To keep them off the network entirely, turn off content capture at the source, for example the AI SDK's recordInputs and recordOutputs, or TRACELOOP_TRACE_CONTENT=false.
• OpenLLMetry for Node does not export failed spans, so those failures do not reach SuperOrgs.

Optional attributes

Standard attributes come first. The superorgs.* attributes are optional and cover only what no convention does.

• user.email or user.id, on a span or resource. Who asked for the run. An email of someone on the customer's org chart links the run to that person, and the run is marked as human requested.
• superorgs.run.title, on a span or resource. The run's title. Without it, the run is named after its agent or span.
• superorgs.run.autonomy, on a span or resource. autonomous or human_requested.
• superorgs.cost.micro_usd, on a model, tool, or agent span. A cost you measured, in integer micro-USD.
• superorgs.cost.estimated, on the same span. true when that figure is your estimate.
• superorgs.cost.source, on the same span. A label for a non-model cost, up to 100 characters.

Responses

• 200. Stored. When some spans were not kept, partial_success says how many and why.
• 400. The body could not be decoded. Do not retry it unchanged.
• 401. The credential is missing, invalid, or revoked.
• 413. The request is too large. Enable gzip or send smaller batches.
• 415. Unsupported Content-Type or Content-Encoding.
• 429. More than 240 requests in a minute for this credential. Retry after the Retry-After seconds.
• 503. A temporary failure. Retry; ingest is idempotent.

Standard OpenTelemetry exporters handle these responses on their own.

Send events

Send a POST with the customer's credential as a bearer token and a JSON body of events. Any HTTP client works, and the Node SDK is a client of the same endpoint.

• Endpoint: POST https://app.superorgs.com/api/agent-stream/v0/events
• Headers: Authorization: Bearer sot_... and Content-Type: application/json
• Body: {"events": [...]}, with 1 to 500 events and at most 8 MB per request.
• Rate limit: 240 requests per minute per credential. At 500 events per request, that is up to 120,000 events a minute.

Event fields

• event_id, required. Your idempotency key, up to 300 characters and unique across the agent's runs. A resent id counts as a duplicate.
• run_external_id, required. Your id for the unit of work, up to 500 characters. Events that share it form one run.
• type, required. One of the 11 event types in the activity schema below.
• occurred_at, required. The ISO 8601 time the event happened, for example 2026-09-17T15:04:00Z.
• payload, optional. An object shaped by the type, up to 256 KB. Defaults to {}.
• run, optional. Run details: title, origin, autonomy, requested_by, model, and metadata (up to 16 KB). The first value of each field is kept, and metadata merges.

Example request

curl -X POST https://app.superorgs.com/api/agent-stream/v0/events \
  -H "Authorization: Bearer $SUPERORGS_STREAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "events": [
    {
      "event_id": "job-42:started",
      "run_external_id": "job-42",
      "type": "run.started",
      "occurred_at": "2026-09-17T15:04:00Z",
      "payload": {},
      "run": {
        "title": "Nightly account sweep",
        "origin": "schedule",
        "autonomy": "autonomous"
      }
    },
    {
      "event_id": "job-42:finished",
      "run_external_id": "job-42",
      "type": "run.finished",
      "occurred_at": "2026-09-17T15:06:12Z",
      "payload": { "summary": "Processed 1,204 records, flagged 12 for review." }
    }
  ]
}'

Responses

• 202. Stored. The body is {accepted, duplicates, rejected, warnings}, and the three counts add up to the events sent.
• 400. The batch is invalid. The body lists the issues.
• 401. The credential is missing, invalid, or revoked.
• 413. The body is over 8 MB.
• 429. More than 240 requests in a minute for this credential. Retry after the Retry-After seconds.
• 5xx. A server error. Retry with backoff.

Resending a batch with the same event ids is always safe. warnings carries stable codes keyed by event id, such as event_id_conflict for a reused id with different content.

On Node 20.3 or newer, @superorgs/sdk wraps this endpoint with batching, retries with backoff, handling of the rate limit, and an optional durable SQLite queue.

The activity schema

This section applies to the Events API. Report each unit of work as one run: run.started, the events along the way, then run.finished or run.error. Nothing is captured automatically, so every event is one your code chose to send.

• run.started. A unit of work begins. Payload {}, with run details in run.
• log. A readable progress line, or a free-form note. {"kind": "progress", "text": "..."} or {"text": "..."}.
• message. A turn of conversation you choose to publish. {"role": "assistant", "text": "..."}.
• tool.call. Your agent calls a tool or an outside system. {"name": "...", "call_id": "...", "args": {...}}.
• tool.result. That call returns. {"name": "...", "call_id": "...", "status": "success", "output": {...}, "duration_ms": 120}.
• cost. Tokens or money for one call or one component of spend. The fields are under Report cost below.
• artifact. The run produced something people can open. {"kind": "...", "title": "...", "url": "https://...", "description": "..."}.
• handoff. Work passes to, or is shared with, another agent in the same workspace. {"to_agent": {"name": "..."}, "role": "handoff", "note": "..."}.
• heartbeat. A long run is still alive. {}.
• run.finished. The run ended well. {"summary": "..."}.
• run.error. The run ended badly. {"message": "..."}.

Four rules the receiver applies:

• Who asked. Set autonomy to autonomous for work your agent started itself, or human_requested with requested_by for work a person asked for. If requested_by is the work email of someone on the customer's org chart, SuperOrgs links the run to that person.
• How a run ends. summary is what people read in the feed until Orion writes its own, and message is the line every surface shows for a failed run. A later end event wins, and on a tie the failure wins.
• Tool results. status is success or error, and duration_ms is a whole number of milliseconds.
• Links. Only http and https URLs render as links. Anything else is kept as text and reported as artifact_url_invalid.

Report cost

Through the Events API, send spend as cost events, one per call or per component of spend, with money in integer micro-USD (1,000,000 is one US dollar).

• input_tokens, output_tokens. Whole-number token counts.
• cache_read_input_tokens. Cached input tokens, optional.
• cost_micro_usd. Integer micro-USD you measured or estimated.
• model. The model name, so SuperOrgs can price tokens.
• estimated. true when the figure is your estimate.
• source. A label for a non-model cost, such as a per-action fee, up to 100 characters.

Example payload:

{"model": "claude-sonnet-4-5", "input_tokens": 18422, "output_tokens": 3110, "cost_micro_usd": 101916, "estimated": false}

• A figure you send is stored as measured, or as an estimate when estimated is true.
• Token-only usage on a model SuperOrgs can price is priced server-side and marked as an estimate. On an unknown model it shows as unpriced, never as free.
• Through OpenTelemetry, token usage on model-call spans is priced the same way. Set superorgs.cost.micro_usd on the span to send a measured figure instead.
• Send each component of spend once. Never send a running total and its parts.
• Flat pricing. If customers pay you a subscription, do not spread it across runs. The customer records the contract price as the agent's monthly cost in SuperOrgs.

Authentication and security

Each credential belongs to one agent in one customer organization, and the credential alone decides where its data lands. The same rules apply to both endpoints.

• Scope. SuperOrgs resolves the organization and the agent from the credential, never from the request body or span attributes. A credential can send everything for its agent, with no narrower scopes.
• Storage. SuperOrgs keeps only a SHA-256 hash of each credential and cannot show it again after minting.
• Rotation. An agent can hold several live credentials. The customer mints a replacement, you switch to it, and they revoke the old one once deliveries show on the new one.
• Revocation. Revoking takes effect immediately. Deleting the agent in SuperOrgs revokes all of its credentials.
• What is stored, Events API. SuperOrgs stores event text as you send it, with no redaction at ingest. Leave out personal data and secrets you do not want stored.
• What is stored, OpenTelemetry. Model names, token counts, tool names, timings, and error types. Prompts, completions, tool arguments, tool results, and error messages are discarded on receipt.
• AI processing. Orion, the SuperOrgs assistant, reads stored run data to write run summaries for the customer.
• Rate limit. Each credential may make up to 240 requests per minute. Past that the endpoint answers 429 with a Retry-After header.

More detail is in the SuperOrgs security model.

Not supported today

SuperOrgs does not offer these today, so plan the integration without them.

• Approval and escalation events. Neither path has an event type for approvals or escalations. Report a wait for a person as a log line.
• A partner-level install. There is no OAuth install or partner-wide credential. Each customer mints one credential per agent.
• Webhooks and polling. SuperOrgs has no endpoint for vendor webhooks, and this integration does not pull from your API or MCP server. Data arrives only through the two endpoints above.
• Other SDK languages. The SDK is Node only. Other stacks use OpenTelemetry or call the Events API directly.
• OpenTelemetry metrics, logs, and gRPC. Only traces are accepted, over HTTP.

Listing and partnership

Once your integration delivers runs for a shared customer, we update your Agent Marketplace listing to say so.

• Listing. Customers browse the Agent Marketplace to find agents to hire for open roles, and can add an agent to their workspace from its listing.
• Featured. The SuperOrgs team may feature a listing, which sorts it first in the catalog and shows a Featured badge. Featuring is an editorial choice and is never sold.
• Co-marketing. We would like to discuss a joint launch, on our blogs and social channels, and mutual referrals on enterprise deals.

Next steps

To begin a SuperOrgs integration:

• Email partners@superorgs.com.
• Docs: agent activity streaming.
• Security model: how SuperOrgs handles your data.
• SDK: @superorgs/sdk on npm.
• First test run. No approval from SuperOrgs is needed. One shared customer, or a SuperOrgs workspace we set up for testing, connects your agent and mints a credential. You send a test run, check for a 202 from the Events API or a 200 from the OpenTelemetry endpoint, and we review the run together.