Send runtime events

Runtime telemetry adds Observed relationships to the inventory. ModelFence receives JSON events from instrumented agents; it does not automatically intercept traffic or install an exporter into your applications.

Create an integration

1. Open Integrations in the correct organization.
2. Create a runtime telemetry integration and give it a recognizable source name.
3. Copy the ingestion endpoint and the token shown for that integration.
4. Store the token in your agent’s secret manager or runtime environment. Do not commit it or paste it into a finding.

Creating or rotating an integration requires Admin or Owner. Runtime telemetry must also be included in the organization’s entitlement. Tokens are scoped to an integration; the ingestion endpoint determines the organization from the token, not a caller-supplied organization ID.

Send a first event

Set MODELFENCE_INGEST_TOKEN securely in your local environment. Create event.json using a current UTC timestamp and a unique event ID:

{
  "events": [
    {
      "id": "tool-call-unique-001",
      "type": "toolCall",
      "timestamp": "2026-10-21T15:00:00Z",
      "agent": "repository-assistant",
      "tool": "read_project_file",
      "model": null,
      "destination": "https://api.example.com",
      "outcome": "success",
      "environment": "development",
      "correlationId": "investigation-001",
      "traceId": null,
      "spanId": null,
      "attributes": {
        "service.name": "repository-assistant",
        "gen_ai.operation.name": "execute_tool"
      }
    }
  ]
}

Replace the sample timestamp before sending. Events older than 30 days or more than five minutes in the future are rejected.

curl --fail-with-body 'https://modelfence.ca/api/v1/ingest/runtime-events' \
  -H "Authorization: Bearer ${MODELFENCE_INGEST_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data-binary @event.json

Use the exact endpoint from your integration when connecting a different deployment. The ingestion API uses a bearer token; ordinary browser session cookies are not a substitute.

Verify the result

The response reports accepted, duplicates, rejected, errors and droppedAttributes. Check the counts, not just HTTP success. Batches can contain at most 500 events. Reusing an event ID within the same integration is treated as a duplicate.

Open Runtime, filter for the agent, and inspect the event’s received time, source and attributes. Follow the asset link to see observed relationships. The integration card should show the latest received activity.

Do not send content bodies

Prompt, completion and payload bodies are not supported. Attributes use an explicit allow-list, including selected gen_ai.*, MCP, service, destination and status fields. Unknown or content-bearing attributes are dropped and counted; accepted values are limited in length. This does not make arbitrary data in agent names, destinations or allowed attributes safe to send. Review instrumentation for secrets and personal information.

Rotate or disconnect

Rotate the token from Integrations, update every sender, and verify new events arrive. The old token is revoked. Disconnect the integration when it should no longer receive data. For errors, see runtime troubleshooting.