How to configure a Web API tile

The Web API plugin allows you to query any REST API that returns JSON and visualize the results directly in a dashboard. This is useful when there isn’t a dedicated SquaredUp plugin available for your data source.

Web API tiles are configured via the tile editor the same as every other data source, however the complexity of the configuration itself can vary significantly depending on the API you are accessing.

In some circumstances, the information you provided when configuring the data source may well suffice to return the data you need. In others, you may be required to include an endpoint, payload, query parameters, headers or paging details.

This guide explains how to configure a basic HTTP request using the HTTP Request data stream in the Web API tile.

Before you begin

Before creating a tile, ensure a Web API data source has already been successfully configured by an administrator.

You will also need to know the full endpoint path and, where applicable, the following details:

  • Any required query parameters
  • Any required headers
  • Whether the request requires a payload (POST requests)
  • Whether pagination is required to return the full dataset

Adding a Web API tile

  1. Open your dashboard.
  2. Click Add
    and select Data
    . The tile editor opens.
  3. On the Data Source tab, select your Web API instance.
  4. On the Data Stream tab, select HTTP request.

Configuring a HTTP request

After selecting the data stream, use the Parameters tab to configure how SquaredUp queries your API endpoint. This includes defining the request method, endpoint path, and any additional parameters required by the API such as headers, query parameters, paging behavior.

The steps you must complete to configure the request are entirely dependent on how the API you are querying is designed. You may see data returned immediately after entering the endpoint path, or you may require additional configuration before a successful response is returned.

For detailed information on each configuration setting, see Web API data stream parameters.

View the request details

Before jumping into configuration, it's a great idea to open the Troubleshooting panel by clicking Open troubleshooting

at the top of the parameters panel.

This panel allows you to clearly view the Response you're getting from your API, as well as the shape of your Request as you configure it.

Configure the endpoint

Use the Basics sub-tab to configure the request method and endpoint URL of the request. The Base URL you entered when configuring the data source is automatically populated in the address (unless you are using a Collection with more than one base URL).

To configure the endpoint:

  1. Method:
    Select GET or POST from the dropdown to the left of the URL.
  2. Enter a path:
    Optionally, enter an endpoint path after the URL.
  3. Click Apply to update the URL and resend the request.

(POST) Provide a payload

If you selected POST as the request method when configuring the request endpoint, you can supply the JSON request payload on the Body sub-tab.

After clicking Apply, you can see that your payload has been added to the Body of your request on Request tab of the Troubleshooting panel.

To provide a payload:

  1. Body:
    Enter a JSON payload. This must match the shape expected by your API.
  2. Click Apply.

Configure query parameters

If you need to provide query parameters in the URL of the request, enter these on the Parameters sub-tab. These are appended to the end of a request URL after a ?.

After clicking Apply, you can view the updated shape of your request URL on Request tab of the Troubleshooting panel.

For example:
https://api.example.com/incidents?status=open&limit=10

To configure query parameters:

  1. Click Add header
    .
  2. Enter the key:value pair to be used.
  3. Optionally, encrypt thevalue by clicking the encrypt icon
    .
  4. Repeat steps 1-3 for each header required.
  5. Click Apply.

Configure headers

If your request requires metadata such as authentication details or content type information, configure this on the Headers sub-tab.

After clicking Apply, you can view the updated shape of your request headers on Request tab of the Troubleshooting panel.

Common headers include:

  • Authorization: Bearer <token>
  • Content-Type: application/json

To configure headers:

  1. Click Add header
    .
  2. Enter the key:value pair to be used.
  3. Optionally, encrypt thevalue by clicking the encrypt icon
    .
  4. Repeat steps 1-3 for each header required.
  5. Click Apply.

Configure paging

Some APIs return results in smaller chunks (“pages”) instead of returning the entire dataset in a single response. If pagination is required, configure the Paging tab to define how SquaredUp should retrieve these additional pages of data.

You can often use the Response tab of the Troubleshooting panel to determine how to configure paging for the request.

For example, in the following image the response body has a parameter named next which contains a link to the next page of results. Therefore, to configure paging:

  • Mode: Select Next URL.
  • NextURL: Select Body and enter next.

To configure paging:

  1. Configure the basic pagination details for the request:
    Parameter
    Description
    Mode
    Select how paging is handled. The correct option to choose depends on the API you are sending the request to. Choose from:
    • None: Paging is disabled.
    • Next URL: Used when a value in the response specifies a URL for the next page of data.
    • Token: Used when a value in the response specifies a token for the next page of data.
    • Offset: Uses a starting value to step through results, one page at a time.
    Page size
    Select how to configure the requested page size. This size can be varied to optimize performance.

    Too many small pages being fetched may cause the tile to time out before all data is received. A page that's too large may cause payload size limits to be exceeded within the SquaredUp app.

    Choose from:
    • None:
      The API’s built-in default page size is used. No page size value is explicitly sent with the request.
    • Body (POST requests only):
      The page size is included in the request body. Use this option when the API expects pagination settings as part of a body.
    • Header:
      The page size is sent in an HTTP header. This is useful when pagination is configured via custom or standard headers.
    • Query parameter:
      The page size is passed as a query string parameter in the request URL (for example, ?pageSize=50).
    Path to page size
    Specify the exact location or name used by the API to read the page size value. Then specify number of records to request per page in the right-hand field. This must be a positive integer and should respect any limits enforced by the API.
  2. Configure the fields that display for your selected Mode:

    Parameter
    Description
    Next URL
    Select where in the response the URL for the next page of results is provided. This URL is used to retrieve the subsequent page without manually constructing pagination parameters.
    • Body: The next page URL is included in the response body. Use this option when the API returns a field containing the full URL for the next page (for example, next, links.next, or pagination.nextUrl).
    • Header: The next page URL is provided in an HTTP response header. This is commonly used for pagination metadata returned outside the response body.
    • Web link: The next page URL is included in a response header using standard web link relations rel="<value>" (for example, next). Use this option when the API follows HTTP link-based pagination conventions.
    After choosing where the next page URL is located, enter the exact path to find the next URL in the right-hand field.

    Parameter
    Description
    Token in response
    Select where in the response the token for fetching the next page can be found. Choose from:
    • Header:
      The pagination token is returned in an HTTP response header. Use this option when the API exposes the token as part of the response metadata.
    • Body:
      The pagination token is included in the response body. This is common when the API returns a token field such as nextToken, cursor, or continuationToken.
    Then, enter the exact path to the incoming token in the right-hand field.
    Token in request
    Select where the pagination token should be inserted in the request to retrieve the next page of results. Choose from:
    • Header:
      The pagination token is sent in an HTTP request header. This is commonly used when the API requires pagination or continuation tokens to be passed in headers.
    • Query parameter:
      The pagination token is sent as a query string parameter in the request URL (for example, ?pageToken=abc123). Use this option when the API expects the token as part of the URL.
    • Body (POST requests only):
      The token is sent in the request body. Use this option when the API expects the token as part of a body.
    Then, enter the exact path to send the token in the right-hand field.

    Parameter
    Description
    Row count
    Select where in the response the total number of rows returned for the current request can be determined. Choose where the row count is located:
    • Body:
      The row count is provided as a value in the response body. Use this option when the API explicitly returns a field containing the number of rows in the current page.
    • Body array size:
      The row count is determined by counting the number of items in an array in the response body. Use this option when the API does not return a separate count field and the page size must be inferred from the array length.
    • Header:
      The row count is provided in an HTTP response header. This is commonly used when pagination metadata is returned outside the response body.
    After selecting the location, enter the exact path to the field or array used to determine the row count in the right-hand field.
    Offset by
    Select how the offset value is calculated for subsequent requests. Choose from:
    • Page:
      The offset represents the page number. Each subsequent request increments the page index.
    • Row:
      The offset represents the number of rows to skip. Each subsequent request increases the offset by the number of rows returned.
    Page / Row
    Select where the page or row offset value is sent in the request. Choose from:
    • Query parameter:
      The offset is sent as a query string parameter in the request URL (for example, ?offset=20 or ?page=3).
    • Header:
      The offset is sent in an HTTP request header. Use this option when the API expects pagination offsets in headers.
    • Body (POST requests only):
      The offset is sent in the request body. Use this option when the API expects the offset as part of a body.
    After selecting the location, enter the exact path used by the API to receive the offset value in the right-hand field.
    Starting offset
    Enter the initial offset value to use for the first request. This value determines where pagination begins and will typically be 1 or 0.

  3. Click Apply.

Transform the response

Response transformation allows you to integrate SquaredUp with even more APIs by transforming response data to fit the needs of your visualizations.

Use the transform tab to specify the path to the data and to optionally apply scripting to the dataset that is returned.

Specify the path to the data in the returned JSON. Choose from:

  • Path: Enter the exact JSON path to select the portion of the response you want to use. For example,
    results
    or
    results[0].value
  • Script: Use a custom JavaScript snippet to transform the response. See data transformation examples for detailed use cases.

To return data from your script, you can use one of the following syntax options: 

result = data.map(a => a.name)

return data.map(a => a.name)

Normalizing an inconsistent API response

This script drills into nested objects, extracts only the useful fields, and outputs a clean array of simple objects. Ideal for visualizations that cannot consume deeply nested structures.

Response JSON:

{
  "meta": { "timestamp": "2025-01-01" },
  "response": {
    "records": [
      {
        "attributes": { "id": 1, "info": { "value": 10 } },
        "status": "ok"
      },
      {
        "attributes": { "id": 2, "info": { "value": 20 } },
        "status": "ok"
      }
    ]
  }
}

Script:

result = data.response.records.map(r => ({
  id: r.attributes.id,
  value: r.attributes.info.value,
  status: r.status
}));

Output JSON:

[
  { "id": 1, "value": 10, "status": "ok" },
  { "id": 2, "value": 20, "status": "ok" }
]

Reshaping API output from multiple nested collections

This example flattens a hierarchical projects > tasks structure into a single list, allowing tables or charts to display all tasks with their related project names.

Response JSON:

{
  "projects": [
    {
      "name": "Alpha",
      "tasks": [
        { "taskId": 1, "hours": 5 },
        { "taskId": 2, "hours": 3 }
      ]
    },
    {
      "name": "Beta",
      "tasks": [
        { "taskId": 3, "hours": 4 }
      ]
    }
  ]
}

Script:

return data.projects.flatMap(project =>
  project.tasks.map(t => ({
    project: project.name,
    taskId: t.taskId,
    hours: t.hours
  }))
);

Output JSON:

[
  { "project": "Alpha", "taskId": 1, "hours": 5 },
  { "project": "Alpha", "taskId": 2, "hours": 3 },
  { "project": "Beta",  "taskId": 3, "hours": 4 }
]

Parsing CSV returned inside JSON

This script converts a CSV string into an array of objects (one per row) so the data can be visualized like any other structured dataset.

Response JSON:

{
  "csv": "time,value\n2024-01-01,10\n2024-01-02,15"
}

Script:

const lines = data.csv.trim().split("\n");
const [header, ...rows] = lines;

const cols = header.split(",");

result = rows.map(line => {
  const values = line.split(",");
  return Object.fromEntries(cols.map((c, i) => [c, values[i]]));
});

Output JSON:

[
  { "time": "2024-01-01", "value": "10" },
  { "time": "2024-01-02", "value": "15" }
]

Adding totals, averages, and ratios

This script calculates new metrics like revenue and averages.

Response JSON:

{
  "sales": [
    { "region": "NA", "units": 120, "price": 5 },
    { "region": "EU", "units": 150, "price": 4 }
  ]
}

Script:

return data.sales.map(s => ({
  region: s.region,
  revenue: s.units * s.price,
  units: s.units,
  price: s.price,
  averageRevenuePerUnit: (s.units * s.price) / s.units
}));

Output JSON:

[
  {
    "region": "NA",
    "revenue": 600,
    "units": 120,
    "price": 5,
    "averageRevenuePerUnit": 5
  },
  {
    "region": "EU",
    "revenue": 600,
    "units": 150,
    "price": 4,
    "averageRevenuePerUnit": 4
  }
]

Complete the tile configuration

From here the standard configuration flow returns and you can configure the tile as any other.

You can:

  • Use the Timeframe tab to apply a timeframe to the data if you supplied an expression during the request config.
  • Filter | Group | Sort the returned data to perform further aggregation.
  • Configure the returned Columns or configure a custom column from the data.
  • Configure a Visualization, Monitor and KPI as required.

HTTP request examples

The following examples show how to configure a HTTP request to query an API. Note that these are for demonstration only and the information you must provide depends on the API.

GET request configuration

This example configuration fetches a list of users from a public API with optional filters.

  1. Basics tab, configure the following:
    • Type: GET
    • URL: https://api.example.com (read-only)
    • Path: /v1/users
  2. On the Parameters tab, configure the following, this defines the following for the resulting request URL https://api.example.com/v1/users?status=active&limit=50:
    Name
    Value
    status
    active
    limit
    50
  3. On the Headers tab, configure the following:
    Name
    Value
    Accept
    application/json
    Authorization
    Bearer {{api_token}}
  4. On the Response tab, configure the following:
    • Response Preview: Click Send to display JSON such as
      {
  "data": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
  ],
  "total": 2
}
    • Select data:
      • Path
      • data
    • Expand Inner Objects: Toggle on to view full user details

POST request configuration

This example configuration sends a query in a POST request to return a list of users from an API.

  1. On the Basics tab, configure the following:
    • Type: POST
    • URL: https://api.example.com (read-only)
    • Path: /v1/sales/query
  2. On the Body tab, configure the following:
    • Body: This request asks the API to return aggregated sales metrics for a specific date range and region
      {
  "startDate": "2025-11-01",
  "endDate": "2025-11-07",
  "region": "North America",
  "metrics": ["totalSales", "averageOrderValue", "transactions"]
}
  3. On the Parameters tab, leave the fields empty, as query parameters are included in the request body for this API.
  4. On the Headers tab, configure the following:
    Name
    Value
    Content-Type
    application/json
    Authorization
    Bearer {{api_token}}
    Accept
    application/json
  5. On the Response tab, configure the following:
    • Response Preview: Click Send to display JSON such as
      {
  "status": "success",
  "data": {
    "summary": {
      "totalSales": 157340.25,
      "averageOrderValue": 78.12,
      "transactions": 2014
    },
    "dailyBreakdown": [
      { "date": "2025-11-01", "totalSales": 22000.50 },
      { "date": "2025-11-02", "totalSales": 24350.00 },
      { "date": "2025-11-03", "totalSales": 18000.75 }
    ]
  }
}
    • Select data:
      • Path
      • data.dailyBreakdown
    • Expand inner objects: Toggle on to view nested objects like summary and dailyBreakdown

Was this article helpful?

Have more questions or facing an issue?
Submit a ticket