---
title: Metadata
description: >-
  Explains what metadata is, how it is transmitted, and what it is used for.
---
{{< youtube id="psYQFbPgIOI" class="youtube-video" title="gRPC metadata limits:The Good, The Bad and The Ugly" >}}
### Overview

Metadata is a side channel that allows clients and servers to provide
information to each other that is associated with an RPC.

gRPC metadata is a key-value pair of data that is sent with initial or final
gRPC requests or responses. It is used to provide additional information about
the call, such as authentication credentials, tracing information, or custom
headers.

gRPC metadata is implemented using HTTP/2 headers. The keys are ASCII
strings, while the values can be either ASCII strings or binary data. The keys
are case insensitive
and must not start with the prefix `grpc-`, which is reserved for gRPC itself.

gRPC metadata can be sent and received by both the client and the server.
Headers are sent from the client to the server before the initial request and
from the server to the client before the initial response of an RPC call.
Trailers are sent by the server when it closes an RPC.

gRPC metadata is useful for a variety of purposes, such as:

* **Authentication**: gRPC metadata can be used to send authentication
  credentials to the server.
  This can be used to implement different authentication schemes, such as `OAuth2`
  or `JWT` using the standard HTTP Authorization header.
* **Tracing**: gRPC metadata can be used to send tracing information to the
  server.
  This can be used to track the progress of a request through a distributed
  system.
* **Custom headers**: gRPC metadata can be used to send custom headers to the
  server or from the server to the client.
  This can be used to implement application-specific features, such as load
  balancing, rate limiting or providing detailed error messages from the server
  to the client.
* **Internal usages**: gRPC uses HTTP/2 headers and trailers, which will be
  integrated with the metadata specified by your application.

See [Core Concepts](/docs/what-is-grpc/core-concepts/#metadata)

#### Be Aware

```
WARNING: Servers may limit the size of Request-Headers, with a default of 8 KiB suggested.
```

Custom metadata must follow the "Custom-Metadata" format listed in
[PROTOCOL-HTTP2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md)
, with the exception of binary headers not needing to be base64 encoded.

#### Headers

Headers are sent before the initial request data message from the client to the
server and similarly before the initial response data from the server to the
client. The header includes things like authentication credentials and how to
handle the RPC. Some of the headers, such as authorization, are generated by
gRPC for you.

Custom header handling is language dependent, generally through
[interceptors](/docs/guides/interceptors/).

#### Trailers

Trailers are a special kind of header that is sent after the message data. They
are used internally to communicate the outcome of an RPC. At the application
level, custom trailers can be used to communicate things not directly part of
the data, such as server utilization and query cost.  Trailers are sent only by
the server.  

### For more details, please see the following gRFCs

* [proposal: G1 true binary metadata][proposal G1]
* [proposal: L7 go metadata api][proposal L7]
* [proposal: L48 node metadata options][proposal L48]
* [proposal: L42 python metadata flags][proposal L42]
* [proposal: L11 ruby interceptors][proposal L11]

### Language Support

| Language | Examples                                   | Notes              |
|----------|--------------------------------------------|--------------------|
| Java     | [Java Header]<br>[Java Error Handling]     |                    |
| Go       | [Go Metadata]<br>[Go Metadata Interceptor] | [Go Documentation] |
| C++      | [C++ Metadata]                             |                    |
| Node     | [Node Metadata]                            |                    |
| Python   | [Python Metadata]                          |                    |
| Ruby     |                                            | Example upcoming   |

[proposal L7]: https://github.com/grpc/proposal/blob/7c05212d14f4abef5f74f71695f95ba8dd3f7dd3/L7-go-metadata-api.md

[proposal G1]: https://github.com/grpc/proposal/blob/7c05212d14f4abef5f74f71695f95ba8dd3f7dd3/G1-true-binary-metadata.md

[proposal L48]: https://github.com/grpc/proposal/blob/7c05212d14f4abef5f74f71695f95ba8dd3f7dd3/L48-node-metadata-options.md

[proposal L42]: https://github.com/grpc/proposal/blob/7c05212d14f4abef5f74f71695f95ba8dd3f7dd3/L42-python-metadata-flags.md

[proposal L11]: https://github.com/grpc/proposal/blob/7c05212d14f4abef5f74f71695f95ba8dd3f7dd3/L11-ruby-interceptors.md

[Java Header]: https://github.com/grpc/grpc-java/tree/master/examples/src/main/java/io/grpc/examples/header

[Java Error Handling]: https://github.com/grpc/grpc-java/tree/master/examples/src/main/java/io/grpc/examples/errorhandling

[Node Metadata]: https://github.com/grpc/grpc-node/tree/master/examples/metadata

[Go Metadata]: https://github.com/grpc/grpc-go/tree/master/examples/features/metadata

[Go Metadata interceptor]: https://github.com/grpc/grpc-go/tree/master/examples/features/metadata_interceptor

[C++ Metadata]: https://github.com/grpc/grpc/tree/master/examples/cpp/metadata

[Python Metadata]: https://github.com/grpc/grpc/tree/master/examples/python/metadata

[Go Documentation]: https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md