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

# gRPC Request

> Execute one native gRPC call and return the response decoded as JSON

The gRPC Request command (Command Type: HTTP, ID: 1005) executes one native gRPC call. It is a unary call, or the first message of a server-streaming method.

## Command Type

**Command Type ID:** 1005 (in an HTTP step)

## Parameters

| Parameter | Type | Description | Required |
| - | - | - | - |
| **url** | string | Target base URL, for example `https://api.example.com:443`. `http://` uses an unencrypted channel. | Yes |
| **service** | string | Fully qualified protobuf service name | Yes |
| **method** | string | RPC method name on the service | Yes |
| **protos** | Protos | The service definition | Yes |
| **body** | object | Request message as JSON, using proto field names | No |
| **headers** | object | Sent as gRPC metadata | No |
| **timeout** | number | gRPC deadline in milliseconds | No |
| **tlsVerify** | boolean | Verify the server certificate (default `true`) | No |
| **bypassGrpcStatus** | Array of string | gRPC status names that do not fail the item. Default `["NOT_FOUND"]` | No |
| **streamMode** | string | `"firstMessage"`, for server-streaming methods only | No |
| **contentType** | string | Only `"JSON"` | No |
| **proxy** | ProxySettings | Proxy settings. The Unblocker is not supported | No |
| **proxyConnectionTimeout** | number | Timeout for proxy connection in milliseconds | No |

There is no `verb`.

### Protos

| Field | Type | Description | Required |
| - | - | - | - |
| **source** | string | One merged `.proto` text with imports inlined | Yes |

## Result

```json theme={null}
{
  "data": { "text": "echo:hi" },
  "response": {
    "grpcStatus": 0,
    "grpcStatusName": "OK",
    "grpcMessage": "",
    "headers": {},
    "trailers": {},
    "data": { "text": "echo:hi" }
  }
}
```

For a bypassed status, `data` is `null` and `grpcStatus` is the bypassed code.

## Usage Examples

### Unary Call

```json theme={null}
{
  "command": "grpc-request",
  "params": {
    "url": "https://api.example.com:443",
    "service": "example.v1.Echo",
    "method": "Unary",
    "contentType": "JSON",
    "body": { "text": "hi" },
    "timeout": 5000,
    "protos": {
      "source": "syntax = \"proto3\";\npackage example.v1;\nmessage EchoRequest { string text = 1; }\nmessage EchoReply { string text = 1; }\nservice Echo { rpc Unary (EchoRequest) returns (EchoReply); }\n"
    }
  }
}
```

### Server Streaming, First Message

```json theme={null}
{
  "command": "grpc-request",
  "params": {
    "url": "https://api.example.com:443",
    "service": "example.v1.Feed",
    "method": "Watch",
    "streamMode": "firstMessage",
    "body": { "topic": "scores" },
    "protos": {
      "source": "syntax = \"proto3\";\npackage example.v1;\nmessage WatchRequest { string topic = 1; }\nmessage Update { string payload = 1; }\nservice Feed { rpc Watch (WatchRequest) returns (stream Update); }\n"
    }
  }
}
```

## Common Errors

| Error | Cause |
| - | - |
| `gRPC service "..." is not defined in the protos` | `service` is not the fully qualified name in `protos.source` |
| `gRPC method "..." is not defined on service` | Method name typo |
| `is client-streaming, which is not supported` | Choose a unary or server-streaming method |
| `Timeout awaiting 'request' for Nms (grpc status: DEADLINE_EXCEEDED (4))` | Raise `timeout` or check the target |
| `... (grpc status: UNAUTHENTICATED (16))` | Missing or expired credential in `headers` |

## Related Commands

* [HTTP Request - Got](https://docs.bringits.com/stream/commands/http/http-request-got.md) - REST single request
* [Parse Commands](https://docs.bringits.com/stream/commands/parse.md) - reshape the decoded response


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.