What headers does Cosmo use for client identification?

Cosmo supports two formats. The vendor-neutral format (recommended) uses GraphQL-Client-Name and GraphQL-Client-Version. The Apollo-compatible format uses ApolloGraphQL-Client-Name and ApolloGraphQL-Client-Version.

Does Cosmo need any configuration to read client headers?

No. The Cosmo Router extracts client identification headers automatically. No configuration changes are required on the Cosmo side.

What happens to requests without client headers?

Requests without identification headers are still tracked in analytics, but they appear without client attribution and cannot be grouped or filtered by client.

Can I use client identification to target deprecation notices?

Yes. Schema Field Usage shows a per-client breakdown for every field, including which clients use it and how often. This data lets you contact exactly the teams affected by a deprecation rather than sending blanket announcements.

What values should I use for client name and version?

Set the GraphQL-Client-Name and GraphQL-Client-Version headers on each request using whatever naming and versioning convention matches your application.

Client Identification for Federated GraphQL | Cosmo by WunderGraph

Q: Which analytics views support client filtering?

Metrics Analytics, Trace Analytics, and Operations Tracking all support filtering by client name and version. Schema Field Usage shows a per-client breakdown for every field — you can see which clients use each field and how often.

The problem

Anonymous traffic makes targeted action impossible

Without knowing which application sent a request, you cannot isolate issues, target communication, or track version adoption.

Anonymous traffic masks the source of issues

When web, mobile, and partner clients share a single API endpoint, traffic is a single undifferentiated stream. Slow responses or elevated error rates could be coming from any of them.

Breaking change communication reaches the wrong people

Without knowing which clients use which fields or operations, teams send deprecation notices to everyone. Most recipients are unaffected. The ones who matter may not pay attention.

Client version drift is invisible

Older client versions may still call deprecated fields or send malformed queries. Without version tracking, you cannot tell how many users are on outdated clients or when it is safe to remove legacy support.

Our solution

Two headers. Full client attribution.

Client Identification requires no Cosmo configuration. Client applications add name and version headers to their requests. The Cosmo Router reads them automatically and propagates client context through every analytics view.

How it works

Client Identification uses HTTP headers to identify client applications and versions on every request.
The Cosmo Router extracts these headers automatically and associates the client data with all telemetry.
All analytics views — metrics, traces, schema field usage, and operations — become client-aware.
Filter metrics, traces, and operations by client name and version.
Group trace analytics by client to see per-application behavior.
Schema Field Usage shows per-client breakdowns for every field.
No additional configuration is required on the Cosmo side beyond deploying the router.

From anonymous traffic to client-aware analytics in minutes.

Client Identification

Before & After

Before Cosmo	With Cosmo
Anonymous traffic with no client attribution	Every request identified by client name and version
Unable to isolate client-specific issues	Filter all analytics by specific client versions
Blanket communication about breaking changes	Targeted communication to clients that use the affected field
No visibility into client version distribution	Track which versions are active across your API

Header formats

Two supported formats

Vendor-neutral (recommended): GraphQL-Client-Name: your-appGraphQL-Client-Version: 1.0.0
Apollo-compatible: ApolloGraphQL-Client-Name: your-appApolloGraphQL-Client-Version: 1.0.0

How Client Identification works

01

Two headers per request.

Add headers

Client applications add two HTTP headers to every GraphQL request: the client name and the client version. No SDK changes or additional setup required on the Cosmo side.

02

Automatic extraction.

Router extracts

The Cosmo Router reads the identification headers from incoming requests and associates the client name and version with all telemetry data for that request.

03

Filter and group everywhere.

Analytics become client-aware

Metrics, traces, and operations support filtering by client name and version. Schema Field Usage shows a per-client breakdown for every field. Group traces by client to see per-application patterns.

04

Per-client deprecation targeting.

Target communication

Use Schema Field Usage to get a list of exactly which clients use a specific field. Reach out to each team with specific usage data rather than a blanket announcement.

What is included

Built into every Cosmo plan

Available on Free, Pro, and Enterprise.

Client-aware analytics

Filter metrics, traces, and operations by client name and version. Schema Field Usage shows a per-client breakdown for every field once headers are in place.

Version tracking

See which client versions are actively making requests to your API. Identify outdated versions still calling deprecated fields before you remove them.

Easy implementation

Two HTTP headers per request. No SDK changes, no Cosmo configuration, no additional services. The router handles extraction automatically.

Ecosystem compatibility

Supports both vendor-neutral headers (recommended) and Apollo-compatible headers. Migrating from Apollo? Your existing header setup works without changes.

Identify your clients across all analytics

Add two headers to your client requests and every analytics view becomes client-aware immediately.

Start Free Read the Docs

Know which clients use your API — and how