> ## Documentation Index > Fetch the complete documentation index at: https://docs.costgraph.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get service map > Returns the observed network edges for the tenant selected by the X-CostGraph-Tenant-ID header, with both endpoints resolved to services and connection counters aggregated over the range. A service is the whole network endpoint record -- id, endpoint_key, resolution_source, tags and timestamps -- plus its kind (the endpoint_key prefix) and the name it resolves to, from inventory for workload, node, vm and container endpoints and derived from the key itself for cloud, class, private and billing ones. Only edges with traffic in the period are included, and the returned service list is derived from the edges that survive filtering. The connection list is sorted and paged, but totals and the service list always describe the whole filtered set, so paging never changes what the summary says. The read range is given by the start and end query parameters; the whole filter is the request body. Filters compose as AND across dimensions and OR within a dimension; omitting a filter means it is not applied. This is a POST only because the filter does not fit a query string -- it reads, and changes nothing ## OpenAPI ````yaml /api-reference/costgraph/openapi.json post /api/v1/tenant/service-map openapi: 3.0.0 info: description: Read and manage your CostGraph organization, spend, alerts, and settings. title: CostGraph API contact: {} version: '1.0' servers: - url: https://api.costgraph.ai security: [] tags: - name: ai x-group: AI - name: ai-serving x-group: AI serving - name: anomalies x-group: Anomalies - name: auth x-group: Auth - name: billing x-group: Billing - name: billing-export x-group: Billing export - name: budgets x-group: Budgets - name: ci x-group: CI - name: compute-recommendations x-group: Compute recommendations - name: config x-group: Config - name: cost x-group: Cost - name: gpus x-group: GPUs - name: graphai x-group: Graph AI - name: infracost x-group: Infracost - name: integrations x-group: Integrations - name: invitations x-group: Invitations - name: kubernetes-clusters x-group: Kubernetes clusters - name: marketplace x-group: Marketplace - name: network-requests x-group: Network requests - name: notifications x-group: Notifications - name: oauth x-group: OAuth - name: oauth-clients x-group: OAuth clients - name: opencost x-group: OpenCost - name: organization x-group: Audit log - name: organizations x-group: Organizations - name: placement-alternatives x-group: Placement alternatives - name: reports x-group: Reports - name: service-map x-group: Service map - name: settings x-group: Settings - name: sso x-group: Single sign-on - name: tenants x-group: Tenants - name: user x-group: Users - name: virtual-machines x-group: Virtual machines - name: virtual-tags x-group: Virtual tags - name: workflows x-group: Workflows paths: /api/v1/tenant/service-map: post: tags: - service-map summary: Get service map description: >- Returns the observed network edges for the tenant selected by the X-CostGraph-Tenant-ID header, with both endpoints resolved to services and connection counters aggregated over the range. A service is the whole network endpoint record -- id, endpoint_key, resolution_source, tags and timestamps -- plus its kind (the endpoint_key prefix) and the name it resolves to, from inventory for workload, node, vm and container endpoints and derived from the key itself for cloud, class, private and billing ones. Only edges with traffic in the period are included, and the returned service list is derived from the edges that survive filtering. The connection list is sorted and paged, but totals and the service list always describe the whole filtered set, so paging never changes what the summary says. The read range is given by the start and end query parameters; the whole filter is the request body. Filters compose as AND across dimensions and OR within a dimension; omitting a filter means it is not applied. This is a POST only because the filter does not fit a query string -- it reads, and changes nothing parameters: - description: Tenant ID name: X-CostGraph-Tenant-ID in: header required: true schema: type: string - description: Range start timestamp in RFC3339 format name: start in: query required: true schema: type: string - description: Range end timestamp in RFC3339 format name: end in: query required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/servicemap.ServiceMapFilter' description: >- Service filter, bounds on each connection's counters for the period, and paging. service_filter.role selects which side of a connection the service filters apply to (client, server, or both; the default keeps a connection when either endpoint matches). limit and offset page the connection list -- limit defaults to 500, is capped at 5000, and a negative limit returns every match. sort_by orders the connections before paging (cost, bytes, connections or failures; cost is the default). Every field is optional and an omitted or null value is not applied, so an empty body or no body at all returns the first page of the unfiltered map responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/responses.SuccessResponse' - type: object properties: data: $ref: '#/components/schemas/servicemap.ServiceMap' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/responses.ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/responses.ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/responses.ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/responses.ErrorResponse' security: - BearerAuth: [] components: schemas: servicemap.ServiceMapFilter: type: object properties: limit: description: A negative Limit is unpaged. type: integer nullable: true max_active_connections: type: integer nullable: true max_bytes_client_to_server: type: number nullable: true max_bytes_server_to_client: type: number nullable: true max_connections_closed: type: integer nullable: true max_connections_opened: type: integer nullable: true max_connections_refused: type: integer nullable: true max_connections_reset: type: integer nullable: true max_observed_seconds: type: number nullable: true max_packets_client_to_server: type: number nullable: true max_packets_server_to_client: type: number nullable: true min_active_connections: type: integer nullable: true min_bytes_client_to_server: type: number nullable: true min_bytes_server_to_client: type: number nullable: true min_connections_closed: type: integer nullable: true min_connections_opened: type: integer nullable: true min_connections_refused: type: integer nullable: true min_connections_reset: type: integer nullable: true min_observed_seconds: type: number nullable: true min_packets_client_to_server: type: number nullable: true min_packets_server_to_client: type: number nullable: true observed_from: type: string offset: type: integer nullable: true service_filter: $ref: '#/components/schemas/servicemap.ServiceFilter' sort_by: type: string enum: - cost - bytes - connections - failures responses.SuccessResponse: type: object required: - message - status properties: data: {} message: type: string example: some message status: type: string example: success servicemap.ServiceMap: type: object properties: connections: type: array items: $ref: '#/components/schemas/servicemap.Connection' range: $ref: '#/components/schemas/servicemap.Range' services: type: array items: $ref: '#/components/schemas/servicemap.Service' totals: description: Covers every filtered connection, not just the returned page. allOf: - $ref: '#/components/schemas/servicemap.ServiceMapTotals' responses.ErrorResponse: type: object required: - message - status properties: message: type: string example: some message status: type: string example: error servicemap.ServiceFilter: type: object properties: resolution_sources: type: array items: type: string role: type: string enum: - client - server - both service_names: type: array items: type: string servicemap.Connection: type: object properties: client: $ref: '#/components/schemas/servicemap.Service' counters: $ref: '#/components/schemas/schema.NetworkReportsHourlyRow' id: type: string metadata: $ref: '#/components/schemas/schema.NetworkReportsRow' server: $ref: '#/components/schemas/servicemap.Service' servicemap.Range: type: object properties: end: type: string start: type: string servicemap.Service: type: object properties: cluster: description: Kubernetes cluster the endpoint belongs to; empty off-cluster. type: string created_at: type: string endpoint_key: type: string group: type: string id: type: string kind: description: Derived from endpoint_key. type: string labels: type: object additionalProperties: type: string name: type: string parent_kind: type: string parent_name: description: >- The resource owning this workload, for a topology view. Empty when the workload is already the root, or the endpoint is not a workload. type: string resolution_source: type: string superseded_by_endpoint_id: type: string tags: type: object tenant_id: type: string updated_at: type: string servicemap.ServiceMapTotals: type: object properties: attributed_cost_monthly: type: number bytes_by_locality: type: object additionalProperties: type: number format: float64 bytes_client_to_server: type: number bytes_server_to_client: type: number cost_attributed_connections: type: integer cost_by_locality: description: |- An absent key means no edge reported that value, not a zero. Reconciliation attributes cost by locality type: object additionalProperties: type: number format: float64 cost_by_mechanism: type: object additionalProperties: type: number format: float64 total_connections: description: Filtered edge count before paging. type: integer total_services: type: integer unhealthy_connections: type: integer schema.NetworkReportsHourlyRow: type: object properties: bucket_start: type: string bytes_client_to_server: type: number bytes_server_to_client: type: number connections_active_max: type: integer connections_closed: type: integer connections_failed: type: integer connections_opened: type: integer connections_refused: type: integer connections_reset: type: integer created_at: type: string id: type: string network_report_id: type: string observed_from: type: string observed_seconds: type: number packets_client_to_server: type: number packets_server_to_client: type: number tenant_id: type: string updated_at: type: string schema.NetworkReportsRow: type: object properties: attributed_cost_monthly: type: number charged_direction: type: string client_az: type: string client_endpoint_id: type: string cost_mechanism: type: string created_at: type: string id: type: string locality: type: string locality_source: type: string nat_translated: type: boolean pricing_source: type: string proto: type: string server_az: type: string server_endpoint_id: type: string server_port: type: number service_vip_observed: type: boolean tags: type: object tenant_id: type: string updated_at: type: string securitySchemes: BearerAuth: description: Enter "Bearer {token}" type: apiKey name: Authorization in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.