---
title: "Configuring Scans using GraphQL API"
slug: "scans-using-graphql-api"
description: "Learn how to programmatically create and manage API security test suites in Traceable using GraphQL APIs. Understand asset selection, traffic configuration, scheduling, and integration setup through structured API requests."
updated: 2025-09-04T13:07:38Z
published: 2025-09-04T13:07:38Z
---

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

# Configuring Scans using GraphQL API

Traceable provides the GraphQL public API for creating and deleting GraphQL schema-based scans (previously suites). To do this, see the following sections:

### Before you begin

Make a note of the following before you proceed with scan creation:

- While the `targetUrl` attribute in the below API request is optional, it becomes mandatory when the traffic type is set to *GENERATED* and the traffic source is either *OpenAPI specifications* or *GraphQL schemas*.
- Make sure that the values for the `environment` and `configuration.trafficEnvironment` attributes are identical.
- To reuse the test scans generated in a previous run, you must specify the value for the `baseScanId` attribute.
- To target specific API endpoints, endpoint labels, or services, you must have the unique identifier (ID) of the underlying asset. Otherwise, the selection automatically includes all available assets.
- When using the GENERATED traffic type, you must have the underlying source’s unique identifier (ID). Otherwise, you must use LIVE.

### Create a scan

To create a scan, use the following sample API request:

```json
mutation {
  createScanSuite(
    create: {
      name: "<name_of_the_suite>"   # It should be unique across enviroments 
      description: ""
      environment: "<enviroment_name>"
      configuration: {
        assetSelections: [   # Attributes in this section cannot be null or empty
          {
            selectionMode: INCLUDE
            selectedAsset: SERVICE/ENDPOINT/FILTER_RULE 
            service: {
              idPredicates: [
                {
                  value: "id1"
                  relationalOperator: EQUALS
                }
                {
                  value: "id2"
                  relationalOperator: EQUALS
                }
                {
                  value: "id3"
                  relationalOperator: EQUALS
                }
              ]
            }
          }
          {
            selectionMode: INCLUDE
            selectedAsset: ENDPOINT
            endpoint: {
              urlPredicates: [
                { relationalOperator: MATCHES_REGEX, value: ".+" }
              ]
            }
          }
          {
            selectionMode: EXCLUDE
            selectedAsset: ENDPOINT
            endpoint: {
              urlPredicates: [
                {
                  relationalOperator: MATCHES_REGEX
                  value: ".*(logout|health).*"
                }
              ]
            }
          }
        ]
        policyId: "id"   # This cannot be null or empty
        targetUrl: ""   # This can be null or empty
        trafficConfiguration: { generationTrafficType:   # This cannot be null or empty 
          LIVE_TRAFFIC 
          #LIVE_TRAFFIC
          #REPLAY_TRAFFIC
          #GENERATED_TRAFFIC   
        }
        trafficEnvironment: "development"   # This cannot be null or empty
        baseScanId: ""   # This can be null or empty
        spanFilters: { conditions: [] }   # This can be null or empty
      }
      advanceConfiguration: {   # This can be null or empty 
        delayDurationBetweenRequests: "PT0S"
        idleTimeoutDuration: "PT600S"
        scanTimeoutDuration: "PT1800S"
        totalTestExecutionThreads: 20
      }
      hookConfiguration: {   # This can be null or empty
        hookDetails: [{ hookId: "id" }]
      }
      integrationDetails: []   # This can be null or empty
      scanEvaluationCriteriaConfiguration: {   # This cannot be null or empty
        scanEvaluationCriteriaDetails: [
          { scanEvaluationCriteriaId: "id" }
        ]
      }
      scheduleJobConfiguration: {   # This can be null or empty
        status: ENABLED
        name: "scheduled"
        runnerIds: []
        dailySchedule: { scheduledTime: "18:30:00.000Z" }
      }
    }
  ) {
    id
    __typename
  }
}
```

Following is the explanation of the attributes in the above API request:

| Attribute | Description |
| --- | --- |
| `name` | The name of the suite |
| `description` | The description of the suite |
| `environment` | The traffic environment of the suite |
| `configuration` | Configure the asset and attack selection rule |
| `configuration.policyId` | ID of the policy for attack selection |
| `configuration.targetUrl` | The target domain |
| `configuration.trafficConfiguration.generationTrafficType` | The traffic type: - `LIVE_TRAFFIC` - `REPLAY_TRAFFIC` - `GENERATED_TRAFFIC` |
| `configuration.trafficEnvironment` | The traffic environment of the suite |
| `configuration.assetSelections.selectionMode` | The selection mode for the assets. This can be either `INCLUDE` or `EXCLUDE`. |
| `configuration.assetSelections.selectedAsset` | This can be: - `ENDPOINT` - `SERVICE` - `FILTER_RULE` |
| `hookConfiguration.hookDetails.hookId` | The hook ID for the suite |
| `integrationDetails` | The integrations you want to use in the suite |
| `scanEvaluationCriteriaConfiguration.scanEvaluationCriteriaDetails.scanEvaluationCriteriaId` | The ID of the scan evaluation criteria |
| `advanceConfiguration.delayDurationBetweenRequests` | The delay duration between the request |
| `advanceConfiguration.idleTimeoutDuration` | The idle timeout duration |
| `advanceConfiguration.totalTestExecutionThreads` | The total threads for execution |
| `scheduleJobConfiguration.status` | If the status is `ENABLE`, it schedules a job on the specified configuration time. |
| `scheduleJobConfiguration.name` | The name of the schedule |
| `scheduleJobConfiguration.runnerIds` | The runner IDs to run the scan |

Following is a sample response to the above API request:

```json
{
  "data": {
    "createScanSuite": {
      "id": "id",
      "__typename": "CreateScanSuiteResponse"
    }
  }
}
```

### Examples

The following are various categories, their respective sample scenarios, and the sample JSON snippets that you can use in your scan creation API request:

#### Asset selection

The asset selection attribute (`selectedAsset`) can use endpoints, services, or rules in scan creation. The following are some scenarios that you can use according to your requirements:

##### **Include URL regex**

```json
{
  selectionMode: INCLUDE
  selectedAsset: ENDPOINT
  endpoint: {
      urlPredicates: [
        { relationalOperator: MATCHES_REGEX, value: ".+" }
    ]
  }
}
```

##### **Exclude URL regex**

```json
Execlude Url Regex asset selection
{
  selectionMode: EXCLUDE
  selectedAsset: ENDPOINT
  endpoint: {
      urlPredicates: [
       {relationalOperator: MATCHES_REGEXvalue: ".*(logout|health).*" }
    ]
  }
}
```

##### **When all API endpoints are selected**

```json
{
  selectionMode: INCLUDE
  selectedAsset: ENDPOINT
  endpoint: { idPredicates: [] }
}
```

##### **When specific API endpoints are selected**

```json
{
 selectionMode: INCLUDE
 selectedAsset: ENDPOINT
   endpoint: {
    idPredicates: [
        {
          value: "id1" 
          relationalOperator: EQUALS
        }
       {
         value: "id2" 
         relationalOperator: EQUALS
       }
    ]
  }
}
```

##### **When endpoint labels are selected**

```json
{
  selectionMode: INCLUDE
  selectedAsset: ENDPOINT
  endpoint: {
      labelPredicates: [
        { value: "Critical", relationalOperator: EQUALS }
        { value: "Sensitive", relationalOperator: EQUALS }
    ]
  }
}
```

##### **When service is selected as an asset**

```json
{
 selectionMode: INCLUDE
 selectedAsset: SERVICE
 service: {
     idPredicates: [
       {
         value: "id3"
         relationalOperator: EQUALS
       }
      {
        value: "id4"
        relationalOperator: EQUALS
      }
    ]
  }
}
```

##### **When assets are selected based on filter rules**

```json
{
 selectionMode: INCLUDE
 selectedAsset: FILTER_RULE
 selectedAssetFilter: [
     {
      keyExpression: { key: "isExternal" }
      operator: EQUALS
      value: true
      type: ATTRIBUTE
     }
    {
      keyExpression: { key: "isAuthenticated" }
      operator: EQUALS
      value: true
      type: ATTRIBUTE
    }
  ]
}
```

#### Traffic configuration

The traffic type selection attribute (`generationTrafficType`) can use live, replay, or generated traffic in scans. Generated traffic can use a Postman collection, an OpenAPI specification, or a GraphQL schema as the source. The following are some scenarios that you can use according to your requirements:

##### When live traffic type is selected

```json
{ generationTrafficType: LIVE_TRAFFIC }
```

##### When replay traffic type is selected

```json
{ generationTrafficType: REPLAY_TRAFFIC }
```

##### When generated traffic type is selected with Postman collection as the source

```json
{
 generationTrafficType: GENERATED_TRAFFIC
 postmanCollectionDetailsList: [
   {
     postmanCollectionId: "id1"
     environmentDocumentId: "id2"   # This attribute is optional 
   }
 ]
}
```

##### When generated traffic type is selected with Open API specs as the source

```json
{
generationTrafficType: GENERATED_TRAFFIC
openApiSpecsIds: ["id1", "id2", "id3"]
}
```

##### When generated traffic type is selected with GraphQL schema as the source

```json
{
generationTrafficType: GENERATED_TRAFFIC
graphqlSchemaDetailsList: [
  {
    graphqlSchemaId: "id1"
    graphqlIntrospectionEnabled: false
   }
   {
    graphqlSchemaId: "id2"
    graphqlIntrospectionEnabled: false
    }
  ]
}
```

#### Hook configuration

You can configure one or more hooks in the scan creation API request, for example:

```json
{
  hookDetails: [
    { hookId: "id1" }
    { hookId: "id2" }
   ]
 }
```

#### Schedule job configuration

The schedule job attribute (`scheduleJobConfiguration`) helps schedule scans to run at specific times. The following is a sample configuration that you can use according to your requirements:

```json
{
 status: ENABLED
 name: "schedule"
 runnerIds: []
 dailySchedule: { scheduledTime: "18:30:00.000Z" }
}
```

The above snippet automatically schedules the scans to run at the specified time (`scheduledTime`) using any available runner. You can also use a specific runner; however, you must specify its ID in the `runnerIds` attribute. You can also schedule the scan to run on a daily, weekly, and monthly basis using the `dailySchedule`, `weeklySchedule`, and `monthlySchedule` attributes respectively.

#### Integration details

The integration details attribute (`integrationDetails`) helps use existing integrations in your test scan, for example:

```json
 {
   snykIntegrationDetails: {
   organizationId: "idO"
   projectIds: ["idP"]
  }
}
```

---

### Delete a scan

To delete a scan (previously suite), use the following sample API request:

```json
mutation {
  deleteScanSuites(scanSuiteIdList: ["id1", "id2"]) {
    success
  }
}
```

Following is the explanation of the attributes in the above API request:

| Attribute | Description |
| --- | --- |
| scanSuiteIdList | List of the suite IDs to delete |

Following is a sample response to the above API request:

```json
{
  "data": {
    "deleteScanSuites": {
      "success": true
    }
  }
}
```

## Related

- [Understanding Scans and Traffic Types](/ast-scans.md)
- [Creating a Scan](/creating-scan.md)
- [Scan Creation Recommendations](/scan-creation-recommendations.md)