---
updatedAt: 2025-09-10T01:20:50.000Z
agentTools:
  projectIndex: https://support.speedcurve.com/llms.txt
---

# Create a snapshot

Add a set of tests for one or multiple sites, or custom URL(s)

## Overview

This endpoint can be used to:

* trigger [on-demand](https://support.speedcurve.com/docs/ondemand-site-testing) testing of a single or multiple websites
* create a [deployment](https://support.speedcurve.com/docs/deployment-testing-synthetic) for site(s)
* add an [adhoc test](https://support.speedcurve.com/docs/adhoc-testing) for a custom URL

## Snapshot vs deploy

**Snapshot** is a set of [on-demand tests](https://support.speedcurve.com/docs/ondemand-site-testing) of your website or custom URLs, submitted at the same time.

**Deployment** (or deploy) is a way to group and add extra information to your snapshots (e.g. name and description), for example, to mark a new version of your code ([deployment](https://support.speedcurve.com/docs/manual-deployment) marks will be present in your charts in SpeedCurve and are supposed to help you to track any performance changes).

There is one-to-one relationship between a site and a snapshot, and a one-to-many relationship between a deploy and a snapshot. Therefore, a deploy can have multiple snapshots each of which might be linked to a site.

Deployment supports **replacing the origin** in your URLs. This is to help you with testing non-production environments that could be deployed to a different host, e.g. staging and development builds. See more in the examples below.

## Adhoc testing

You can initiate [Adhoc (custom URL) testing](https://support.speedcurve.com/docs/adhoc-testing) using this endpoint by omitting `sites` parameter and passing the following adhoc settings (that become required if `sites` is not present):

* `urls`(array of objects): list of URLs you would like to test
* `regions`(array of objects): list of regions (locations) to run adhoc tests from. Use **Region ID** from [this list](https://support.speedcurve.com/docs/test-agent-locations) to pass as `region_id`. You can use private region ID if you have one.
* `test_profiles`(array of objects): list of test profiles (browsers), including custom profiles. Use browser name from your settings page to pass as `name` parameter, for example `Desktop Slow`. [Default test profiles](https://support.speedcurve.com/docs/browsers-and-devices#default-browsers)

Please see examples of JSON body for adhoc testing below.

## Example JSON requests

### Single site testing

Start on-demand testing of individual site (with the test settings used for scheduled testing of the site)

```json
{
    "sites": [
        {
            "site_id": 123
        }
    ]
}
```

### Single site deployment

Add a [deployment](https://support.speedcurve.com/docs/manual-deployment) for a site

```json
{
  "sites": [
    {
      "site_id": 123
    }
  ],
  "deploy": {
    "name": "Update React to v18.2.0"
  }
}
```

### Multiple sites testing

Start an on-demand testing of multiple sites. This will create a separate snapshot for each site

```json
{
    "sites": [
        {
            "site_id": 123
        },
        {
            "site_id": 456
        }
    ]
}
```

### Test individual URL(s) of existing site

Start on-demand testing of one or more individual URLs within an existing site (with the test settings used for scheduled testing of the site).

The following example will trigger tests for two URLs  of site ID123 using settings (browsers and regions) specified for that site:

```json
{
    "sites": [
        {
            "site_id": 123,
            "urls": [
              {
                "url_id": 456
              },
              {
                "url_id": 789
              }
            ]
        }
    ]
}
```

### Adhoc testing

Start an [adhoc test](https://support.speedcurve.com/docs/adhoc-testing) for one or more custom URLs, regions and test profiles. Optionally specify synthetic test script and [HTTP Basic auth](https://support.speedcurve.com/docs/test-pages-requiring-authentication) credentials for the URL(s).

```json
{
    "urls": [
        {
            "url": "https://www.speedcurve.com/about",
            "script": null,
            "auth": 
            {
                "username": null,
                "password": null
            }
        }
    ],
    "regions": [
        {
            "region_id": "ap-southeast-1"
        }
    ],
    "test_profiles": [
        {
            "name": "Firefox"
        }, 
        {
            "name": "Chrome Beta"
        }
    ]
}
```

### Adhoc deployment

Pass optional `deploy`object to create a [deployment](https://support.speedcurve.com/docs/deployment-testing-synthetic) for this round of adhoc tests. Might be useful to track your deployments if you use CI/CD process to trigger adhoc performance testing.

```json
{
    "urls": [
        {
            "url": "https://www.speedcurve.com/about",
        },
        {
            "url": "https://www.speedcurve.com/"
        }
    ],
    "regions": [
        {
            "region_id": "ap-southeast-1"
        }
    ],
    "test_profiles": [
        {
            "name": "Desktop Slow"
        }, 
        {
            "name": "Mobile Medium"
        }
    ],
    "deploy": {
        "name": "v130",
      	"description": "Commit f0fda58630310a6dd91a7d8f0a4ceda2"
    }
}
```

### Deploy a different environment (replace URL origin)

**Replacing the origin** in your URLs can help you test staging and development builds when you need to work with an environment different from production, using the settings already present in your project.

The term "origin" refers to the combination of a scheme (protocol, such as HTTP or HTTPS), a hostname, and a port (if specified). For example, given the URL `https://www.example.com:443/foo`, the origin is `https://www.example.com:443`.

To swap the origin in all URLs of your site, send the `deploy[environment_origin]` parameter with your request. For example, replacing the origin in the URL `https://www.example.com/foo` with `https://staging.example.com` will result in testing `https://staging.example.com/foo` instead of the original URL defined in the site settings.

The following is the request payload example:

```json
{
    "sites": [
        {
            "site_id": 123
        }
    ],
    "deploy": {
        "name": "PR #876 Remove lazy load from category page banner",
        "environment_name": "staging",
        "environment_origin": "https://staging.example.com"
    }
}
```

Please see [GitHub Integration](https://support.speedcurve.com/docs/github-integration) page for automating your deployments created as part of GitHub pull requests.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "speedcurve-api-v2-beta",
    "version": "2.1.0"
  },
  "servers": [
    {
      "url": "https://api.speedcurve.com/v2"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/accounts/{account_id}/snapshots": {
      "post": {
        "summary": "Create a snapshot",
        "description": "Add a set of tests for one or multiple sites, or custom URL(s)",
        "operationId": "create-a-snapshot",
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "description": "Account ID",
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "required": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sites": {
                    "type": "array",
                    "description": "Site(s) to create snapshots for",
                    "items": {
                      "properties": {
                        "site_id": {
                          "type": "integer",
                          "description": "Site ID",
                          "format": "int32"
                        },
                        "urls": {
                          "type": "array",
                          "items": {
                            "properties": {
                              "url_id": {
                                "type": "integer",
                                "description": "URL ID",
                                "format": "int32"
                              }
                            },
                            "type": "object"
                          }
                        }
                      },
                      "type": "object"
                    }
                  },
                  "urls": {
                    "type": "array",
                    "items": {
                      "properties": {
                        "url": {
                          "type": "string",
                          "description": "Full URL (starting with http)"
                        },
                        "script": {
                          "type": "string",
                          "description": "Synthetic test script for the URL (see https://support.speedcurve.com/docs/synthetic-test-scripts)"
                        },
                        "auth": {
                          "type": "object",
                          "properties": {
                            "username": {
                              "type": "string",
                              "description": "HTTP Basic auth username"
                            },
                            "password": {
                              "type": "string",
                              "description": "HTTP Basic auth password"
                            }
                          }
                        }
                      },
                      "type": "object"
                    }
                  },
                  "regions": {
                    "type": "array",
                    "items": {
                      "properties": {
                        "region_id": {
                          "type": "string",
                          "description": "Region (test location) ID (see https://support.speedcurve.com/docs/test-agent-locations)"
                        }
                      },
                      "type": "object"
                    }
                  },
                  "test_profiles": {
                    "type": "array",
                    "items": {
                      "properties": {
                        "name": {
                          "type": "string",
                          "description": "Test profile (browser) name (from the list of available profiles including custom browsers, see https://support.speedcurve.com/docs/browsers-and-devices#default-browsers)"
                        }
                      },
                      "type": "object"
                    }
                  },
                  "test_runs": {
                    "type": "integer",
                    "description": "Number of runs (checks) for each test (default 3; max 10)",
                    "format": "int32"
                  },
                  "deploy": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "description": "Deployment name"
                      },
                      "description": {
                        "type": "string",
                        "description": "Deployment description"
                      },
                      "environment_name": {
                        "type": "string",
                        "description": "Name of environment if different from the original site"
                      },
                      "environment_origin": {
                        "type": "string",
                        "description": "Origin if different from the original site in settings (all URLs origin will be replaced with provided)"
                      }
                    }
                  },
                  "force": {
                    "type": "boolean",
                    "description": "Skip the testing in progress check for the site(s) (accepts true/false or 1/0), default `false`"
                  }
                }
              },
              "examples": {
                "Single site testing": {
                  "value": {
                    "sites": [
                      {
                        "site_id": 123
                      }
                    ]
                  }
                },
                "Single site deployment": {
                  "value": {
                    "sites": [
                      {
                        "site_id": 123
                      }
                    ],
                    "deploy": {
                      "name": "Update React to v18.2.0"
                    }
                  }
                },
                "Multiple sites testing": {
                  "value": {
                    "sites": [
                      {
                        "site_id": 123
                      },
                      {
                        "site_id": 456
                      }
                    ]
                  }
                },
                "Adhoc testing": {
                  "value": {
                    "urls": [
                      {
                        "url": "https://www.speedcurve.com/about",
                        "script": null,
                        "auth": {
                          "username": null,
                          "password": null
                        }
                      }
                    ],
                    "regions": [
                      {
                        "region_id": "ap-southeast-1"
                      }
                    ],
                    "test_profiles": [
                      {
                        "name": "Firefox"
                      },
                      {
                        "name": "Chrome Beta"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "OK": {
                    "value": "{\n  \"data\": [\n    {\n      \"snapshot_id\": 123456789,\n      \"site_id\": 123,\n      \"deploy_id\": null,\n      \"timestamp\": 1710822413,\n      \"tests\": [\n        {\n          \"test_id\": \"240319_WS_d12345abc67890bca3a205a4e7e1e6\"\n        },\n        {\n          \"test_id\": \"272502_BO_hsD23453a205a4e7e16abc67890bca\"\n        }\n      ]\n    }\n  ]\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "snapshot_id": {
                            "type": "integer",
                            "example": 123456789,
                            "default": 0
                          },
                          "site_id": {
                            "type": "integer",
                            "example": 123,
                            "default": 0
                          },
                          "deploy_id": {},
                          "timestamp": {
                            "type": "integer",
                            "example": 1710822413,
                            "default": 0
                          },
                          "tests": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "test_id": {
                                  "type": "string",
                                  "example": "240319_WS_d12345abc67890bca3a205a4e7e1e6"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "testing in progress": {
                    "value": "{\n    \"message\": \"Site testing is currently in progress. Only one on-demand test at a time is allowed on a specific site.\",\n    \"errors\": {\n        \"site_id\": [\n            \"Site ID123 The Guardian Production is currently being tested. Please try again later.\"\n        ]\n    }\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Site testing is currently in progress. Only one on-demand test at a time is allowed on a specific site."
                    },
                    "errors": {
                      "type": "object",
                      "properties": {
                        "site_id": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "example": "Site ID123 The Guardian Production is currently being tested. Please try again later."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "403",
            "content": {
              "application/json": {
                "examples": {
                  "not enough checks": {
                    "value": "{\n    \"message\": \"Monthly synthetic checks quota exceeded.\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Monthly synthetic checks quota exceeded."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "422",
            "content": {
              "application/json": {
                "examples": {
                  "validation error(s)": {
                    "value": "{\n    \"message\": \"Request parameters are not valid.\",\n    \"errors\": {\n        \"test_profiles\": [\n            \"The test profiles field is required when urls is present.\"\n        ]\n    }\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Request parameters are not valid."
                    },
                    "errors": {
                      "type": "object",
                      "properties": {
                        "test_profiles": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "example": "The test profiles field is required when urls is present."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```