> ## Documentation Index
> Fetch the complete documentation index at: https://moonshotfactory.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Service map

> Auto-discovered topology of all services and agents communicating in your system — built from trace data with no manual configuration required.

The service map gives you a visual overview of how your services and AI agents connect to each other. It is built automatically from the span data you send to AgentVista — no configuration files, no manual topology definitions.

<Note>
  The service map requires trace data to exist. If you have just created your account or have not yet ingested any traces, the map will be empty. Start the [quickstart](/quickstart) to send your first trace.
</Note>

## How it works

Every time a span is ingested, AgentVista records its `parent_span_id`. When a span from service A has a child span in service B, that means A called B. The service map aggregates all of these parent-child relationships across all your traces and renders them as a directed graph:

* **Nodes** represent individual services and agents
* **Edges** represent call relationships, directed from caller to callee
* **Edge weight** is the number of spans that crossed that relationship (call volume)

The map refreshes automatically as new trace data flows in.

## Node types

Every node has a `node_type` derived from the span type that produced it:

| Node type  | Produced by span type | Examples                                            |
| ---------- | --------------------- | --------------------------------------------------- |
| `agent`    | `agent` spans         | Your AI agents instrumented with the AgentVista SDK |
| `service`  | `http` spans          | REST APIs, microservices, internal HTTP services    |
| `database` | `db` spans            | PostgreSQL, Redis, any database query span          |
| `external` | `custom` spans        | Third-party APIs, external services                 |

AI agents appear as first-class nodes on the map, placed alongside your infrastructure services. A single map can show you an agent calling an internal API, which in turn queries a database — the full call chain in one view.

## Time range filtering

By default, the map shows topology derived from traces in the last 24 hours. You can change this using the `hours` query parameter:

```bash theme={null}
# Last 24 hours (default)
GET /api/v1/dashboard/service-map/?hours=24

# Last 7 days
GET /api/v1/dashboard/service-map/?hours=168

# All time
GET /api/v1/dashboard/service-map/?hours=0
```

The dashboard UI provides a time range picker that maps to the same parameter.

## API response format

```json theme={null}
{
  "nodes": [
    {
      "id": "support-agent",
      "name": "support-agent",
      "node_type": "agent",
      "span_type": "agent",
      "span_count": 1240
    },
    {
      "id": "user-service",
      "name": "user-service",
      "node_type": "service",
      "span_type": "http",
      "span_count": 3820
    },
    {
      "id": "postgres-main",
      "name": "postgres-main",
      "node_type": "database",
      "span_type": "db",
      "span_count": 9100
    }
  ],
  "edges": [
    {
      "source": "support-agent",
      "target": "user-service",
      "weight": 1240
    },
    {
      "source": "user-service",
      "target": "postgres-main",
      "weight": 3820
    }
  ]
}
```

Each node's `id` and `name` match the service name or agent name used in the span data. The `span_count` tells you how active that node was in the selected time window. Edge `weight` reflects the number of spans observed crossing that relationship.

## Common use cases

<CardGroup cols={2}>
  <Card title="Dependency discovery" icon="diagram-project">
    Ask "which services does my agent depend on?" — the map shows you every downstream dependency your agent touches, including any you may have missed during development.
  </Card>

  <Card title="Traffic flow analysis" icon="arrow-right-arrow-left">
    See how traffic flows through your system. Identify which services carry the most call volume and which are potential bottlenecks.
  </Card>

  <Card title="Unexpected connections" icon="triangle-exclamation">
    Spot call relationships you did not expect — for example, an agent calling a service it should not, or a service making calls to an external API that bypasses your intended architecture.
  </Card>

  <Card title="Incident scoping" icon="magnifying-glass">
    When an agent starts failing, check the service map to quickly identify which downstream services are in its call path and narrow down where the problem may originate.
  </Card>
</CardGroup>