Skip to main content

Query Request History

When a request is sent to a Beeceptor endpoint, it's stored for future review. Beeceptor collects diverse data from each HTTP request including headers and payload. To streamline the retrieval and management of request history, the following APIs available.

Get All Requests

Use this API to retrieve one or multiple HTTP requests. You can pass query parameters to precisely filter and narrow down your search to the specific requests you need.

Request Details

MethodRequest Path
GEThttps://api.beeceptor.com/api/v1/endpoints/<my-endpoint>/requests
  • <my-endpoint> - name of the Beeceptor endpoint

Query Params For Filtering

Supported query parameters and their sample values:

  • path=SOME-REQUEST-PATH - This parameter allows you to retrieve all requests with a matching path. By default, the input is treated as a regular expression. In case the regular expression parsing fails, the input is searched as-is, ensuring a seamless search experience.
  • status=200 - Use this parameter to filter requests that have a response with a 200 status code. Any code between 200 and 599 is considered valid. If an invalid value is passed, this filter will be ignored.
  • method=POST - Use this parameter to filter requests matching given HTTP method.
  • dateFrom=2019-10-20T18:19:48.851Z - Specify this parameter to retrieve requests that occurred after the specified date and time. The format for the date and time is ISO format, with the UTC timezone.
  • dateTo=2019-10-20T18:19:48.851Z - Use this parameter to retrieve requests that occurred before the specified date and time. The format for the date and time should be in ISO format, with the UTC timezone.
  • reqBody=SOME-VALUE - This parameter allows you to retrieve all the items where the request payload contains given value. You can either pass a search value or a regular expression. If the input is a valid regular expression, it is given priority for search.
  • resBody=SOME-VALUE - This parameter allows you to retrieve all the items where the response payload contains given value. You can either pass a search value or a regular expression. If the input is a valid regular expression, it is given priority for search.
  • mode=full - By default, the API returns only basic details. However, by sending mode as full, you can retrieve both the request and response body.
  • count=20 - By default, only 20 results are returned. However, you can increase this number up to a maximum of 500 requests.

API Response Definition

The API response holds an array of requests in data parameter. Refer the table below for details about each attribute in response.

Response parametersDetails
idUniquely identifies a request.
dateDate and time at which the server received this request (ISO format in UTC timezone).
timeTakenTotal time taken in milliseconds measured at server-side.
statusResponse status code.
methodRequest method (GET, POST, PUT, etc)
pathRequest path including any query and path parameters.
ruletrue, if a mocking rule was matched for this request.
req.bRequest body, represented as text. (This is available with full details mode)
req.hA map of all the request headers. The header keys are case-insensitive and available in lower case. (This is available with full details mode)
res.bResponse body, represented as text. (This is available with full details mode)
res.hA map of all the response headers. The header keys are case-insensitive and available in lower case. (This is available with full details mode)

If a mock rule is matched during the generation of a specific response, you can identify the rule by checking for the x-beeceptor-rule-id header in the response object. This header provides a unique identifier for the rule responsible for the response.

Example - Retrieve requests meta details (compact mode)

A success response has 200 as HTTP status code.

{
"data": [
{
"id": "tabejjdc5wg",
"date": "2023-11-02T12:07:17.350Z",
"method": "GET",
"path": "/random-responses",
"rule": true,
"status": 505,
"timeTaken": 37
},
{
"id": "1kjuikmdna3",
"date": "2023-11-02T12:07:12.263Z",
"method": "POST",
"path": "/post-for-templated-response?address=Hyderabad",
"rule": true,
"status": 202,
"timeTaken": 5028
},
{
"id": "wowrmm3j09b",
"date": "2023-11-02T12:07:10.178Z",
"method": "GET",
"path": "/get-me-templated-data",
"rule": true,
"status": 202,
"timeTaken": 2017
},
{
"id": "x0rhjp29nij",
"date": "2023-11-02T12:07:10.113Z",
"method": "GET",
"path": "/any-get",
"rule": true,
"status": 299,
"timeTaken": 9
},
{
"id": "1ne2rk3c6kd",
"date": "2023-11-02T12:07:09.057Z",
"method": "PATCH",
"path": "/some-prefix-path?name=jain",
"rule": true,
"status": 200,
"timeTaken": 1005
},
{
"id": "bp55bcuypke",
"date": "2023-11-02T12:07:09.009Z",
"method": "GET",
"path": "/exact-path-match",
"rule": true,
"status": 200,
"timeTaken": 5
},
{
"id": "9fokif642tw",
"date": "2023-11-02T12:07:08.956Z",
"method": "POST",
"path": "/",
"rule": true,
"status": 200,
"timeTaken": 5
},
{
"id": "fk8fg0hjeyh",
"date": "2023-11-02T12:07:08.894Z",
"method": "POST",
"path": "/",
"rule": true,
"status": 200,
"timeTaken": 5
},
{
"id": "o8mn538rt5j",
"date": "2023-11-02T12:07:08.737Z",
"method": "PATCH",
"path": "/some-prefix-path",
"rule": true,
"status": 200,
"timeTaken": 11
},
{
"id": "06kma28nokuc",
"date": "2023-11-02T12:06:31.052Z",
"method": "GET",
"path": "/random-responses",
"rule": true,
"status": 505,
"timeTaken": 6
},
{
"id": "7fchhyao3wk",
"date": "2023-11-02T12:06:15.270Z",
"method": "GET",
"path": "/random-responses",
"rule": true,
"status": 200,
"timeTaken": 8
},
{
"id": "3t5bcpnd0oo",
"date": "2023-11-02T12:06:11.932Z",
"method": "GET",
"path": "/random-responses",
"rule": true,
"status": 200,
"timeTaken": 3
},
{
"id": "6sn5jxzny8f",
"date": "2023-11-02T12:06:07.546Z",
"method": "GET",
"path": "/random-responses",
"rule": true,
"status": 200,
"timeTaken": 11
},
{
"id": "nk6cvy1fpm",
"date": "2023-11-02T12:05:32.084Z",
"method": "GET",
"path": "/random-responses",
"rule": true,
"status": 505,
"timeTaken": 7
},
{
"id": "xaqvh1fwt",
"date": "2023-11-02T12:05:31.376Z",
"method": "GET",
"path": "/random-responses",
"rule": true,
"status": 200,
"timeTaken": 3
},
{
"id": "qo3upsf28b",
"date": "2023-11-02T12:05:30.727Z",
"method": "GET",
"path": "/random-responses",
"rule": true,
"status": 505,
"timeTaken": 6
},
{
"id": "9j2h5yble4",
"date": "2023-11-02T12:05:29.406Z",
"method": "GET",
"path": "/random-responses",
"rule": true,
"status": 505,
"timeTaken": 5
},
{
"id": "xje5hxg5hm",
"date": "2023-11-02T12:05:26.834Z",
"method": "GET",
"path": "/random-responses",
"rule": true,
"status": 200,
"timeTaken": 30
},
{
"id": "2c1vjzf86dy",
"date": "2023-11-02T12:04:03.383Z",
"method": "GET",
"path": "/random-responses",
"rule": true,
"status": 505,
"timeTaken": 7
},
{
"id": "03cvarpxz5ra",
"date": "2023-11-02T12:03:50.055Z",
"method": "GET",
"path": "/random-responses",
"rule": true,
"status": 505,
"timeTaken": 4
}
]
}

Example - Retrieve all details (with mode=full)

A success response has 200 as HTTP status code.

{
"data": [
{
"id": "48ifhrbwedo",
"date": "2019-10-20T18:19:48.851Z",
"timeTaken": 22,
"method": "POST",
"path": "/my/api/path",
"status": 200,
"rule": false,
"req": {
"b": "{\"data\":\"Hello Beeceptor\"}",
"h": {
"host": "test-endpoint.free.localhost:8008",
"user-agent": "curl/7.54.0",
"accept": "*/*",
"content-type": "application/json",
"content-length": "26"
}
},
"res": {
"b": "\nHey ya! Great to see you here. Btw, nothing is configured for this request path. Create a rule and start building a mock API.\n",
"h": {
"content-type": "text/plain",
"access-control-allow-origin": "*",
"vary": "Accept-Encoding"
}
}
},
{
"id": "03vi2qc3fh79",
"date": "2019-10-20T18:20:10.399Z",
"timeTaken": 4,
"method": "POST",
"path": "/my/api/path/some/path",
"status": 200,
"rule": false,
"req": {
"b": "{\"data\":\"Hello Beeceptor\"}",
"h": {
"host": "test-endpoint.free.localhost:8008",
"user-agent": "curl/7.54.0",
"accept": "*/*",
"content-type": "application/json",
"content-length": "26"
}
},
"res": {
"b": "\nHey ya! Great to see you here. Btw, nothing is configured for this request path. Create a rule and start building a mock API.\n",
"h": {
"content-type": "text/plain",
"access-control-allow-origin": "*",
"vary": "Accept-Encoding"
}
}
},
{
"id": "6zgmmaebb5d",
"date": "2019-10-20T18:21:17.846Z",
"timeTaken": 6,
"method": "POST",
"path": "/my/api/path",
"status": 404,
"rule": true,
"req": {
"b": "{\"data\":\"Hello Beeceptor\"}",
"h": {
"host": "test-endpoint.free.localhost:8008",
"user-agent": "curl/7.54.0",
"accept": "*/*",
"content-type": "application/json",
"content-length": "26"
}
},
"res": {
"b": "Some error occurred.",
"h": {
"access-control-allow-origin": "*",
"content-type": "text/plain",
"vary": "Accept-Encoding"
}
}
}
]
}

Get One Request

Returns one request matching the given request ID.

Endpoint

HTTP MethodRequest Path
GEThttps://api.beeceptor.com/api/v1/endpoints/<my-endpoint>/requests/<request-id>
  • <my-endpoint> - name of the Beeceptor endpoint
  • <request-id> - request's id

Success Response

The following represents a success response with 200 as HTTP status code.

{
"data": [
{
"id": "48ifhrbwedo",
"date": "2019-10-20T18:19:48.851Z",
"timeTaken": 22,
"method": "POST",
"path": "/my/api/path",
"status": 200,
"rule": false,
"req": {
"b": "{\"data\":\"Hello Beeceptor\"}",
"h": {
"host": "test-endpoint.free.localhost:8008",
"user-agent": "curl/7.54.0",
"accept": "*/*",
"content-type": "application/json",
"content-length": "26"
}
},
"res": {
"b": "\nHey ya! Great to see you here. Btw, nothing is configured for this request path. Create a rule and start building a mock API.\n",
"h": {
"content-type": "text/plain",
"access-control-allow-origin": "*",
"vary": "Accept-Encoding"
}
}
}
]
}

Purge Requests

Use this API to delete or purge request history. Note that deleting requests is non-recoverable.

Request Details

MethodRequest Path
DELETEhttps://api.beeceptor.com/api/v1/endpoints/<my-endpoint>/requests

Deletes all requests for this endpoint
DELETEhttps://api.beeceptor.com/api/v1/endpoints/<my-endpoint>/requests/<request-id>

Deletes one request with given ID for this endpoint
  • <my-endpoint> - name of the Beeceptor endpoint.
  • <request-id> - request's id, to delete a specific request. When request-id is not passed, all requests will be deleted.

Success Response

A success response has 200 as HTTP status code. In the following requestsPurged represents number of requests purged with this API call.

{
"data": {
"requestsPurged": 1
}
}

Limitations

  • Requests sent in last 10 days are available for retrieval.
  • Binary content is not supported by this API.
  • Delete/purging requests is non-recoverable.