HTTP Request Builder: Methods, Bodies, and Headers

Every HTTP interaction in a Gatling simulation starts with the http(requestName) builder. The request name serves as the key for aggregating statistics in reports — requests sharing the same name across different scenario steps are combined. Once built, requests are passed to exec() to be attached to the scenario flow. All parameters throughout the builder — URLs, headers, body content — accept static strings, Gatling Expression Language (EL) strings, or session functions.

Request Name

// static name
http("requestName").get("https://gatling.io");
// dynamic name from EL
http("#{requestName}").get("https://gatling.io");
// dynamic name from function
http(session -> session.getString("requestName")).get("https://gatling.io");

Request names can be dynamic, but avoid generating a very high number of distinct values. Too many unique request names place a heavy burden on the reporting module and dilute statistics to the point of meaninglessness.

HTTP Methods

Gatling provides built-in methods for the most common HTTP verbs. All of them accept absolute URLs, Gatling EL strings, or session functions.

http("name").get("https://gatling.io");
http("name").get("#{url}");
http("name").get(session -> session.getString("url"));

http("name").put("https://gatling.io");
http("name").post("https://gatling.io");
http("name").delete("https://gatling.io");
http("name").head("https://gatling.io");
http("name").patch("https://gatling.io");
http("name").options("https://gatling.io");
// custom HTTP method
http("name").httpRequest("PURGE", "http://myNginx.com");

Gatling also supports relative URLs when a baseUrl is defined on the HTTP protocol. See the Protocol page for details.

Query Parameters

Query parameters can be passed inline in the URL string or added individually via queryParam. Keys and values are URL-encoded by default.

// inline in URL
http("Issues")
  .get("https://github.com/gatling/gatling/issues?milestone=1&state=open");

// via queryParam
http("Issues").get("https://github.com/gatling/gatling/issues")
  .queryParam("milestone", "1")
  .queryParam("state", "open");

// with EL strings
http("Issues").get("https://github.com/gatling/gatling/issues")
  .queryParam("milestone", "#{milestoneValue}")
  .queryParam("state", "#{stateValue}");

// multiple values for a single key
http("name").get("/")
  .multivaluedQueryParam("param", List.of("value1", "value2"));

// multiple params at once
http("name").get("/")
  .queryParamSeq(List.of(
    Map.entry("key1", "value1"),
    Map.entry("key2", "value2")
  ));

Headers

Add request-level headers that override or extend those set on the protocol. Gatling provides shortcut methods for common content type encodings.

Map<String, String> sentHeaders = new HashMap<>();
sentHeaders.put("content-type", "application/javascript");
sentHeaders.put("accept", "text/html");

http("name").get("/")
  .headers(sentHeaders)
  .header("keep-alive", "150")
  .header("content-type", "application/json");

Content Type Shortcuts (`asXXX`)

Gatling provides shorthand methods that set the appropriate Accept and Content-Type headers in one call.

// sets Accept: application/json and Content-Type: application/json
http("name").post("/").asJson();

// sets Accept: application/xhtml+xml and Content-Type: application/xhtml+xml
http("name").post("/").asXml();

// sets Content-Type: application/x-www-form-urlencoded
http("name").post("/").asFormUrlEncoded();

// sets Content-Type: multipart/form-data
http("name").post("/").asMultipartForm();

To exclude headers set on the HttpProtocol for a single request, use ignoreProtocolHeaders.

Checks

Add response checks to an individual request. These run in addition to any checks defined at the protocol level. Use ignoreProtocolChecks to skip protocol-level checks for a specific request.

http("name").get("/")
  .check(status().is(200));

// skip protocol checks for this request
http("name").get("/")
  .ignoreProtocolChecks();

Request Body

Body templates are resolved from the classpath. Place files under src/main/resources or src/test/resources in Maven/Gradle/sbt projects and reference them with a classpath path (e.g., data/payload.json), not a relative filesystem path.

Pass a text payload defined inline. The charset is taken from the Content-Type header, or from gatling.conf if not set. Supports static strings, EL strings, and functions.

// static payload
http("name").post("/")
  .body(StringBody("{ \"foo\": \"staticValue\" }"));

// EL string payload
http("name").post("/")
  .body(StringBody("{ \"foo\": \"#{dynamicValue}\" }"));

// function payload
http("name").post("/")
  .body(StringBody(session ->
    "{ \"foo\": \"" + session.getString("dynamicValueKey") + "\" }"
  ));

Send raw file bytes as-is. This is the most efficient body type because bytes are cached and not transcoded. Suitable for binary protocols like Protobuf.

http("name").post("/")
  .body(RawFileBody("rawPayload.json"));

// with EL path
http("name").post("/")
  .body(RawFileBody("#{payloadPath}"));

Load a text template from the classpath and resolve Gatling EL expressions within it before sending.

http("name").post("/")
  .body(ElFileBody("payload.json"));

http("name").post("/")
  .body(ElFileBody("#{payloadPath}"));

Use the Pebble templating engine for conditional blocks and loops that Gatling EL cannot express.

http("name").post("/")
  .body(PebbleStringBody(
    "{ \"foo\": \"{% if someCondition %}{{someValue}}{% endif %}\" }"
  ));

Load a Pebble template from a classpath file and resolve it before sending. Supports template inheritance, unlike PebbleStringBody.

http("name").post("/")
  .body(PebbleFileBody("pebbleTemplate.json"));

// with EL path
http("name").post("/")
  .body(PebbleFileBody("#{templatePath}"));

Pass a raw byte array, useful for binary protocols.

http("name").post("/")
  .body(ByteArrayBody(new byte[] { 0, 1, 5, 4 }));

// decode Base64 from session
http("name").post("/")
  .body(ByteArrayBody(session ->
    Base64.getDecoder().decode(session.getString("data"))
  ));

Pass a java.io.InputStream as the request body. The stream is read once and not cached, so use a function that produces a new stream for each virtual user.

http("name").post("/")
  .body(InputStreamBody(session ->
    new java.io.ByteArrayInputStream(new byte[] { 0, 1, 5, 4 })
  ));

InputStreamBody is not supported in the JavaScript/TypeScript SDK.

Pre-processing: `processRequestBody`

Transform the request body before it is written to the wire. Currently, Gatling provides gzipBody as a built-in preprocessor.

http("name").post("/")
  .body(RawFileBody("file"))
  .processRequestBody(gzipBody);

Forms

`formParam` / `multivaluedFormParam`

Send application/x-www-form-urlencoded data field by field. Gatling automatically sets the Content-Type header unless you override it.

http("name").post("/")
  .formParam("milestone", "1")
  .formParam("state", "open");

// multi-value
http("name").post("/")
  .multivaluedFormParam("param", List.of("value1", "value2"));

// bulk
http("name").post("/")
  .formParamSeq(List.of(
    Map.entry("key1", "value1"),
    Map.entry("key2", "value2")
  ));

`form`

Repost all inputs from a form that was previously captured via a form check. Individual fields can be overridden with formParam.

http("name").post("/")
  .form("#{previouslyCapturedForm}")
  .formParam("fieldToOverride", "newValue");

`formUpload`

Upload files as multipart form parts. Gatling automatically switches the Content-Type to multipart/form-data when at least one file part is present.

http("name").post("/")
  .formParam("key", "value")
  .formUpload("file1", "file1.dat")
  .formUpload("file2", "file2.dat");

// with EL path
http("name").post("/")
  .formUpload("file1", "#{file1Path}");

Multipart Body Parts

For fine-grained multipart control, use bodyPart or bodyParts with typed part builders.

// single part
http("name").post("/")
  .bodyPart(StringBodyPart("partName", "value"));

// multiple parts
http("name").post("/")
  .bodyParts(
    StringBodyPart("partName1", "value"),
    StringBodyPart("partName2", "value")
  );

// with options
http("name").post("/")
  .bodyPart(
    StringBodyPart("partName", "value")
      .contentType("text/plain")
      .charset("utf-8")
      .fileName("fileName")
      .dispositionType("form-data")
      .contentId("contentId")
      .transferEncoding("base64")
      .header("name", "value")
  );

Available part types mirror the full body types: StringBodyPart, RawFileBodyPart, ElFileBodyPart, PebbleStringBodyPart, PebbleFileBodyPart, and ByteArrayBodyPart.

Concurrent Resources

Attach subordinate resource requests to a main request. They are fetched concurrently (capped by maxConnectionsPerHost for HTTP/1.1, uncapped for HTTP/2) and the scenario pauses until all complete.

http("name").get("/")
  .resources(
    http("api.js").get("/assets/api.js"),
    http("ga.js").get("/ga.js")
  );

Concurrent Requests

Execute a standalone group of requests concurrently outside of a main request context. Use httpConcurrentRequests when you want to fire multiple independent requests at the same time without any parent request. Concurrency follows the same rules as resources — capped by maxConnectionsPerHost for HTTP/1.1 and uncapped for HTTP/2.

exec(
  httpConcurrentRequests(
    http("Request 1").get("/api?param=value1"),
    http("Request 2").get("/api?param=value2")
  )
);

Advanced Options

`requestTimeout`

Override the global gatling.http.requestTimeout for an individual request — useful for large file uploads or slow endpoints.

http("name").get("/")
  .requestTimeout(Duration.ofMinutes(3));

`silent` / `notSilent`

Mark a request as silent so it is excluded from reports and error triggers, or mark a specific resource as not silent when resources are globally silenced.

http("name").get("/").silent();

// mark a specific resource as not silent
http("name").get("/")
  .resources(
    http("resource").get("/assets/images/img1.png").notSilent()
  );

`transformResponse`

Process the response before it enters the checks pipeline. The example below decodes a Base64-encoded response body.

http("name").post("/")
  .transformResponse((response, session) -> {
    if (response.status().code() == 200) {
      return new io.gatling.http.response.Response(
        response.request(),
        response.startTimestamp(),
        response.endTimestamp(),
        response.status(),
        response.headers(),
        new io.gatling.http.response.ByteArrayResponseBody(
          Base64.getDecoder().decode(response.body().string()),
          StandardCharsets.UTF_8
        ),
        response.checksums(),
        response.isHttp2()
      );
    } else {
      return response;
    }
  });

HTTP Protocol

Other Protocols

Session & Data

HTTP Request Builder: Methods, Bodies, and Headers

Request Name

HTTP Methods

Query Parameters

Headers

Content Type Shortcuts (`asXXX`)

Checks

Request Body

Pre-processing: `processRequestBody`

Forms

`formParam` / `multivaluedFormParam`

`form`

`formUpload`

Multipart Body Parts

Concurrent Resources

Concurrent Requests

Advanced Options

`requestTimeout`

`silent` / `notSilent`

`transformResponse`

Build docs developers (and LLMs) love

HTTP Protocol

Other Protocols

Session & Data

Documentation Index

​Request Name

​HTTP Methods

​Query Parameters

​Headers

​Content Type Shortcuts (asXXX)

​Checks

​Request Body

​Pre-processing: processRequestBody

​Forms

​formParam / multivaluedFormParam

​form

​formUpload

​Multipart Body Parts

​Concurrent Resources

​Concurrent Requests

​Advanced Options

​requestTimeout

​silent / notSilent

​transformResponse

Build docs developers (and LLMs) love

Request Name

HTTP Methods

Query Parameters

Headers

Content Type Shortcuts (`asXXX`)

Checks

Request Body

Pre-processing: `processRequestBody`

Forms

`formParam` / `multivaluedFormParam`

`form`

`formUpload`

Multipart Body Parts

Concurrent Resources

Concurrent Requests

Advanced Options

`requestTimeout`

`silent` / `notSilent`

`transformResponse`