> For the complete documentation index see https://domscan.net/llms.txt. Markdown versions of every docs page are available by appending .md to the page URL.

Source: https://domscan.net/ko/docs/products/batch-jobs

# 비동기 API 배치 API 레퍼런스

클라이언트 연결을 계속 열어 두지 않고도 지원되는 여러 API 요청을 대기열에 넣고 결과를 수집할 수 있습니다. 이 레퍼런스에서 알맞은 엔드포인트를 고르고 반환되는 결과를 정확히 확인하세요.

[제품 페이지 보기](https://domscan.net/ko/async-batch-api)

## 작업

POST `/v1/batches` [API 레퍼런스 보기](https://domscan.net/ko/docs/products/batch-jobs#createApiBatch)

GET `/v1/batches` [API 레퍼런스 보기](https://domscan.net/ko/docs/products/batch-jobs#listApiBatches)

GET `/v1/batches/:job_id` [API 레퍼런스 보기](https://domscan.net/ko/docs/products/batch-jobs#getApiBatch)

GET `/v1/batches/:job_id/results` [API 레퍼런스 보기](https://domscan.net/ko/docs/products/batch-jobs#getApiBatchResults)

DELETE `/v1/batches/:job_id` [API 레퍼런스 보기](https://domscan.net/ko/docs/products/batch-jobs#cancelApiBatch)

GET `/v1/jobs` [API 레퍼런스 보기](https://domscan.net/ko/docs/products/batch-jobs#listJobs)

GET `/v1/jobs/:job_id` [API 레퍼런스 보기](https://domscan.net/ko/docs/products/batch-jobs#getJob)

GET `/v1/jobs/:job_id/results` [API 레퍼런스 보기](https://domscan.net/ko/docs/products/batch-jobs#getJobResults)

POST `/v1/jobs/:job_id/cancel` [API 레퍼런스 보기](https://domscan.net/ko/docs/products/batch-jobs#cancelJob)

POST `/v1/estimate` [API 레퍼런스 보기](https://domscan.net/ko/docs/products/batch-jobs#estimateRequestCost)

POST `/v1/feedback` [API 레퍼런스 보기](https://domscan.net/ko/docs/products/batch-jobs#sendFeedback)

## POST `/v1/batches`

작업: `createApiBatch`
크레딧 및 인증: 무료
인증 필요

POST /v1/batches 크레딧: 0

#### 본문 매개변수

| 매개변수 | 유형 | 필수 |
| --- | --- | --- |
| notify_webhook | unknown | 선택 사항 |
| requests | object[] | 필수 |
| webhook | object | 선택 사항 |

#### 응답 필드

| 필드 | 유형 |
| --- | --- |
| `job` | object |
| `job.id` | string |
| `job.status` | string |
| `job.total` | integer |
| `job.counts` | object |
| `job.counts.pending` | integer |
| `job.counts.processing` | integer |
| `job.counts.succeeded` | integer |
| `job.counts.failed` | integer |
| `job.counts.cancelled` | integer |
| `job.billing` | object |
| `job.billing.credits_charged` | integer |
| `job.billing.credits_refunded` | integer |
| `job.billing.credits_net` | integer |
| `job.webhook` | object |
| `job.webhook.configured` | boolean |
| `job.webhook.status` | string |
| `job.webhook.attempts` | integer |
| `job.status_url` | string |
| `job.results_url` | string |
| `job.results_csv_url` | string |
| `job.poll_after_ms` | integer \| null |
| `job.created_at` | string |
| `job.started_at` | string \| null |
| `job.completed_at` | string \| null |
| `job.cancelled_at` | string \| null |
| `job.updated_at` | string |
| `job.processing_deadline_at` | string |
| `job.results_expires_at` | string |

#### 예제 요청

```bash
curl -X POST "https://domscan.net/v1/batches" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{
  "requests": [
    {
      "path": "/v1/status",
      "query": {
        "domain": "example.com"
      },
      "reference": "customer-42"
    },
    {
      "path": "/v1/dns",
      "query": {
        "domain": "example.org",
        "type": "MX"
      }
    }
  ],
  "webhook": {
    "url": "https://example.com/hooks/domscan",
    "secret": "replace-with-a-private-secret"
  }
}'
```

```javascript
const response = await fetch("https://domscan.net/v1/batches", {
  method: "POST",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "requests": [
      {
        "path": "/v1/status",
        "query": {
          "domain": "example.com"
        },
        "reference": "customer-42"
      },
      {
        "path": "/v1/dns",
        "query": {
          "domain": "example.org",
          "type": "MX"
        }
      }
    ],
    "webhook": {
      "url": "https://example.com/hooks/domscan",
      "secret": "replace-with-a-private-secret"
    }
  }),
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.post(
    "https://domscan.net/v1/batches",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={
        "requests": [
            {
                "path": "/v1/status",
                "query": {
                    "domain": "example.com",
                },
                "reference": "customer-42",
            },
            {
                "path": "/v1/dns",
                "query": {
                    "domain": "example.org",
                    "type": "MX",
                },
            },
        ],
        "webhook": {
            "url": "https://example.com/hooks/domscan",
            "secret": "replace-with-a-private-secret",
        },
    },
)
print(response.json())
```

```go
package main

func main() {
	body := strings.NewReader(`{
	  "requests": [
	    {
	      "path": "/v1/status",
	      "query": {
	        "domain": "example.com"
	      },
	      "reference": "customer-42"
	    },
	    {
	      "path": "/v1/dns",
	      "query": {
	        "domain": "example.org",
	        "type": "MX"
	      }
	    }
	  ],
	  "webhook": {
	    "url": "https://example.com/hooks/domscan",
	    "secret": "replace-with-a-private-secret"
	  }
	}`)
	req, err := http.NewRequest(http.MethodPost, "https://domscan.net/v1/batches", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/batches")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "requests" => [
    {
      "path" => "/v1/status",
      "query" => {
        "domain" => "example.com"
      },
      "reference" => "customer-42"
    },
    {
      "path" => "/v1/dns",
      "query" => {
        "domain" => "example.org",
        "type" => "MX"
      }
    }
  ],
  "webhook" => {
    "url" => "https://example.com/hooks/domscan",
    "secret" => "replace-with-a-private-secret"
  }
})

#### 예제 응답

```json
{
  "job": {
    "id": "example-id",
    "status": "queued",
    "total": 1,
    "counts": {
      "pending": 1,
      "processing": 1,
      "succeeded": 1,
      "failed": 1,
      "cancelled": 1
    },
    "billing": {
      "credits_charged": 1,
      "credits_refunded": 1,
      "credits_net": 1
    },
    "webhook": {
      "configured": false,
      "status": "not_configured",
      "attempts": 1
    },
    "status_url": "https://example.com",
    "results_url": "https://example.com",
    "results_csv_url": "https://example.com",
    "created_at": "2026-08-27T12:00:00Z",
    "updated_at": "2026-08-27T12:00:00Z",
    "processing_deadline_at": "2026-08-27T12:00:00Z",
    "results_expires_at": "2026-08-27T12:00:00Z",
    "poll_after_ms": 1,
    "started_at": "2026-08-27T12:00:00Z",
    "completed_at": "2026-08-27T12:00:00Z",
    "cancelled_at": "2026-08-27T12:00:00Z"
  }
}
```

#### HTTP 상태 코드

- `200` 성공
- `202` 수락됨
- `400` 잘못된 요청
- `401` 인증되지 않음
- `402` 결제 필요
- `409` HTTP 409
- `429` 요청 과다

## GET `/v1/batches`

작업: `listApiBatches`
크레딧 및 인증: 무료
인증 필요

GET /v1/batches 크레딧: 0

#### 쿼리 매개변수

| 매개변수 | 유형 | 필수 |
| --- | --- | --- |
| limit | integer 기본값 `25` | 선택 사항 |

#### 응답 필드

| 필드 | 유형 |
| --- | --- |
| `jobs[]` | object[] |
| `jobs[]` | object |
| `jobs[].id` | string |
| `jobs[].status` | string |
| `jobs[].total` | integer |
| `jobs[].counts` | object |
| `jobs[].counts.pending` | integer |
| `jobs[].counts.processing` | integer |
| `jobs[].counts.succeeded` | integer |
| `jobs[].counts.failed` | integer |
| `jobs[].counts.cancelled` | integer |
| `jobs[].billing` | object |
| `jobs[].billing.credits_charged` | integer |
| `jobs[].billing.credits_refunded` | integer |
| `jobs[].billing.credits_net` | integer |
| `jobs[].webhook` | object |
| `jobs[].webhook.configured` | boolean |
| `jobs[].webhook.status` | string |
| `jobs[].webhook.attempts` | integer |
| `jobs[].status_url` | string |
| `jobs[].results_url` | string |
| `jobs[].results_csv_url` | string |
| `jobs[].poll_after_ms` | integer \| null |
| `jobs[].created_at` | string |
| `jobs[].started_at` | string \| null |
| `jobs[].completed_at` | string \| null |
| `jobs[].cancelled_at` | string \| null |
| `jobs[].updated_at` | string |
| `jobs[].processing_deadline_at` | string |
| `jobs[].results_expires_at` | string |
| `retention_hours` | integer |

#### 예제 요청

```bash
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/batches?limit=25"
```

```javascript
const response = await fetch("https://domscan.net/v1/batches?limit=25", {
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY },
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.get(
    "https://domscan.net/v1/batches?limit=25",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
)
print(response.json())
```

```go
package main

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://domscan.net/v1/batches?limit=25", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/batches?limit=25")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")

#### 예제 응답

```json
{
  "jobs": [
    {
      "id": "example-id",
      "status": "queued",
      "total": 1,
      "counts": {
        "pending": 1,
        "processing": 1,
        "succeeded": 1,
        "failed": 1,
        "cancelled": 1
      },
      "billing": {
        "credits_charged": 1,
        "credits_refunded": 1,
        "credits_net": 1
      },
      "webhook": {
        "configured": false,
        "status": "not_configured",
        "attempts": 1
      },
      "status_url": "https://example.com",
      "results_url": "https://example.com",
      "results_csv_url": "https://example.com",
      "created_at": "2026-08-27T12:00:00Z",
      "updated_at": "2026-08-27T12:00:00Z",
      "processing_deadline_at": "2026-08-27T12:00:00Z",
      "results_expires_at": "2026-08-27T12:00:00Z",
      "poll_after_ms": 1,
      "started_at": "2026-08-27T12:00:00Z",
      "completed_at": "2026-08-27T12:00:00Z",
      "cancelled_at": "2026-08-27T12:00:00Z"
    }
  ],
  "retention_hours": 24
}
```

#### HTTP 상태 코드

- `200` 성공
- `400` 잘못된 요청
- `401` 인증되지 않음
- `429` 요청 과다

## GET `/v1/batches/:job_id`

작업: `getApiBatch`
크레딧 및 인증: 무료
인증 필요

GET /v1/batches/:job_id 크레딧: 0

#### 쿼리 매개변수

| 매개변수 | 유형 | 필수 |
| --- | --- | --- |
| job_id | string | 필수 |

#### 응답 필드

| 필드 | 유형 |
| --- | --- |
| `job` | object |
| `job.id` | string |
| `job.status` | string |
| `job.total` | integer |
| `job.counts` | object |
| `job.counts.pending` | integer |
| `job.counts.processing` | integer |
| `job.counts.succeeded` | integer |
| `job.counts.failed` | integer |
| `job.counts.cancelled` | integer |
| `job.billing` | object |
| `job.billing.credits_charged` | integer |
| `job.billing.credits_refunded` | integer |
| `job.billing.credits_net` | integer |
| `job.webhook` | object |
| `job.webhook.configured` | boolean |
| `job.webhook.status` | string |
| `job.webhook.attempts` | integer |
| `job.status_url` | string |
| `job.results_url` | string |
| `job.results_csv_url` | string |
| `job.poll_after_ms` | integer \| null |
| `job.created_at` | string |
| `job.started_at` | string \| null |
| `job.completed_at` | string \| null |
| `job.cancelled_at` | string \| null |
| `job.updated_at` | string |
| `job.processing_deadline_at` | string |
| `job.results_expires_at` | string |

#### 예제 요청

```bash
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/batches/string"
```

```javascript
const response = await fetch("https://domscan.net/v1/batches/string", {
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY },
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.get(
    "https://domscan.net/v1/batches/string",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
)
print(response.json())
```

```go
package main

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://domscan.net/v1/batches/string", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/batches/string")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")

#### 예제 응답

```json
{
  "job": {
    "id": "example-id",
    "status": "queued",
    "total": 1,
    "counts": {
      "pending": 1,
      "processing": 1,
      "succeeded": 1,
      "failed": 1,
      "cancelled": 1
    },
    "billing": {
      "credits_charged": 1,
      "credits_refunded": 1,
      "credits_net": 1
    },
    "webhook": {
      "configured": false,
      "status": "not_configured",
      "attempts": 1
    },
    "status_url": "https://example.com",
    "results_url": "https://example.com",
    "results_csv_url": "https://example.com",
    "created_at": "2026-08-27T12:00:00Z",
    "updated_at": "2026-08-27T12:00:00Z",
    "processing_deadline_at": "2026-08-27T12:00:00Z",
    "results_expires_at": "2026-08-27T12:00:00Z",
    "poll_after_ms": 1,
    "started_at": "2026-08-27T12:00:00Z",
    "completed_at": "2026-08-27T12:00:00Z",
    "cancelled_at": "2026-08-27T12:00:00Z"
  }
}
```

#### HTTP 상태 코드

- `200` 성공
- `401` 인증되지 않음
- `404` 찾을 수 없음
- `429` 요청 과다

## GET `/v1/batches/:job_id/results`

작업: `getApiBatchResults`
크레딧 및 인증: 무료
인증 필요

GET /v1/batches/:job_id/results 크레딧: 0

#### 쿼리 매개변수

| 매개변수 | 유형 | 필수 |
| --- | --- | --- |
| job_id | string | 필수 |
| after | integer 기본값 `-1` | 선택 사항 |
| limit | integer 기본값 `100` | 선택 사항 |
| format | string 허용된 값 `json`, `csv` 기본값 `json` | 선택 사항 |

#### 응답 필드

| 필드 | 유형 |
| --- | --- |
| `job` | object |
| `job.id` | string |
| `job.status` | string |
| `job.total` | integer |
| `job.counts` | object |
| `job.counts.pending` | integer |
| `job.counts.processing` | integer |
| `job.counts.succeeded` | integer |
| `job.counts.failed` | integer |
| `job.counts.cancelled` | integer |
| `job.billing` | object |
| `job.billing.credits_charged` | integer |
| `job.billing.credits_refunded` | integer |
| `job.billing.credits_net` | integer |
| `job.webhook` | object |
| `job.webhook.configured` | boolean |
| `job.webhook.status` | string |
| `job.webhook.attempts` | integer |
| `job.status_url` | string |
| `job.results_url` | string |
| `job.results_csv_url` | string |
| `job.poll_after_ms` | integer \| null |
| `job.created_at` | string |
| `job.started_at` | string \| null |
| `job.completed_at` | string \| null |
| `job.cancelled_at` | string \| null |
| `job.updated_at` | string |
| `job.processing_deadline_at` | string |
| `job.results_expires_at` | string |
| `results[]` | object[] |
| `results[]` | object |
| `results[].position` | integer |
| `results[].reference` | string \| null |
| `results[].request` | object |
| `results[].request.method` | string |
| `results[].request.path` | string |
| `results[].request.query` | object |
| `results[].status` | string |
| `results[].attempts` | integer |
| `results[].http_status` | integer \| null |
| `results[].result` | object \| null |
| `results[].error` | object \| null |
| `results[].billing` | object |
| `results[].started_at` | string \| null |
| `results[].completed_at` | string \| null |
| `next_after` | integer \| null |

#### 예제 요청

```bash
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/batches/example/results?after=-1&limit=25&format=json"
```

```javascript
const response = await fetch("https://domscan.net/v1/batches/example/results?after=-1&limit=25&format=json", {
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY },
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.get(
    "https://domscan.net/v1/batches/example/results?after=-1&limit=25&format=json",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
)
print(response.json())
```

```go
package main

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://domscan.net/v1/batches/example/results?after=-1&limit=25&format=json", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/batches/example/results?after=-1&limit=25&format=json")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")

#### 예제 응답

```json
{
  "job": {
    "id": "example-id",
    "status": "queued",
    "total": 1,
    "counts": {
      "pending": 1,
      "processing": 1,
      "succeeded": 1,
      "failed": 1,
      "cancelled": 1
    },
    "billing": {
      "credits_charged": 1,
      "credits_refunded": 1,
      "credits_net": 1
    },
    "webhook": {
      "configured": false,
      "status": "not_configured",
      "attempts": 1
    },
    "status_url": "https://example.com",
    "results_url": "https://example.com",
    "results_csv_url": "https://example.com",
    "created_at": "2026-08-27T12:00:00Z",
    "updated_at": "2026-08-27T12:00:00Z",
    "processing_deadline_at": "2026-08-27T12:00:00Z",
    "results_expires_at": "2026-08-27T12:00:00Z",
    "poll_after_ms": 1,
    "started_at": "2026-08-27T12:00:00Z",
    "completed_at": "2026-08-27T12:00:00Z",
    "cancelled_at": "2026-08-27T12:00:00Z"
  },
  "results": [
    {
      "position": 1,
      "request": {
        "method": "GET",
        "path": "example",
        "query": {}
      },
      "status": "pending",
      "attempts": 1,
      "http_status": 1,
      "result": {},
      "error": {},
      "billing": {},
      "reference": "example",
      "started_at": "2026-08-27T12:00:00Z",
      "completed_at": "2026-08-27T12:00:00Z"
    }
  ],
  "next_after": 1
}
```

#### HTTP 상태 코드

- `200` 성공
- `400` 잘못된 요청
- `401` 인증되지 않음
- `404` 찾을 수 없음
- `429` 요청 과다

## DELETE `/v1/batches/:job_id`

작업: `cancelApiBatch`
크레딧 및 인증: 무료
인증 필요

DELETE /v1/batches/:job_id 크레딧: 0

#### 쿼리 매개변수

| 매개변수 | 유형 | 필수 |
| --- | --- | --- |
| job_id | string | 필수 |

#### 응답 필드

| 필드 | 유형 |
| --- | --- |
| `job` | object |
| `job.id` | string |
| `job.status` | string |
| `job.total` | integer |
| `job.counts` | object |
| `job.counts.pending` | integer |
| `job.counts.processing` | integer |
| `job.counts.succeeded` | integer |
| `job.counts.failed` | integer |
| `job.counts.cancelled` | integer |
| `job.billing` | object |
| `job.billing.credits_charged` | integer |
| `job.billing.credits_refunded` | integer |
| `job.billing.credits_net` | integer |
| `job.webhook` | object |
| `job.webhook.configured` | boolean |
| `job.webhook.status` | string |
| `job.webhook.attempts` | integer |
| `job.status_url` | string |
| `job.results_url` | string |
| `job.results_csv_url` | string |
| `job.poll_after_ms` | integer \| null |
| `job.created_at` | string |
| `job.started_at` | string \| null |
| `job.completed_at` | string \| null |
| `job.cancelled_at` | string \| null |
| `job.updated_at` | string |
| `job.processing_deadline_at` | string |
| `job.results_expires_at` | string |

#### 예제 요청

```bash
curl -X DELETE "https://domscan.net/v1/batches/string" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{}'
```

```javascript
const response = await fetch("https://domscan.net/v1/batches/string", {
  method: "DELETE",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.delete(
    "https://domscan.net/v1/batches/string",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={},
)
print(response.json())
```

```go
package main

func main() {
	body := strings.NewReader(`{}`)
	req, err := http.NewRequest(http.MethodDelete, "https://domscan.net/v1/batches/string", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/batches/string")
request = Net::HTTP::Delete.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({})

#### 예제 응답

```json
{
  "job": {
    "id": "example-id",
    "status": "queued",
    "total": 1,
    "counts": {
      "pending": 1,
      "processing": 1,
      "succeeded": 1,
      "failed": 1,
      "cancelled": 1
    },
    "billing": {
      "credits_charged": 1,
      "credits_refunded": 1,
      "credits_net": 1
    },
    "webhook": {
      "configured": false,
      "status": "not_configured",
      "attempts": 1
    },
    "status_url": "https://example.com",
    "results_url": "https://example.com",
    "results_csv_url": "https://example.com",
    "created_at": "2026-08-27T12:00:00Z",
    "updated_at": "2026-08-27T12:00:00Z",
    "processing_deadline_at": "2026-08-27T12:00:00Z",
    "results_expires_at": "2026-08-27T12:00:00Z",
    "poll_after_ms": 1,
    "started_at": "2026-08-27T12:00:00Z",
    "completed_at": "2026-08-27T12:00:00Z",
    "cancelled_at": "2026-08-27T12:00:00Z"
  }
}
```

#### HTTP 상태 코드

- `202` 수락됨
- `401` 인증되지 않음
- `404` 찾을 수 없음
- `409` HTTP 409
- `429` 요청 과다

## GET `/v1/jobs`

작업: `listJobs`
크레딧 및 인증: 무료
인증 필요

GET /v1/jobs 크레딧: 0

#### 쿼리 매개변수

| 매개변수 | 유형 | 필수 |
| --- | --- | --- |
| limit | integer 기본값 `25` | 선택 사항 |
| cursor | string | 선택 사항 |
| kind | string 허용된 값 `batch`, `tech_scan`, `scrape`, `domain_discovery`, `crawl` | 선택 사항 |

#### 응답 필드

| 필드 | 유형 |
| --- | --- |
| `jobs[]` | object[] |
| `jobs[]` | object |
| `jobs[].id` | string |
| `jobs[].kind` | string |
| `jobs[].status` | string |
| `jobs[].native_status` | string |
| `jobs[].created_at` | string \| null |
| `jobs[].updated_at` | string \| null |
| `jobs[].started_at` | string \| null |
| `jobs[].completed_at` | string \| null |
| `jobs[].results_expires_at` | string \| null |
| `jobs[].progress` | object |
| `jobs[].progress.total` | integer |
| `jobs[].progress.done` | integer |
| `jobs[].progress.succeeded` | integer |
| `jobs[].progress.failed` | integer |
| `jobs[].progress.cancelled` | integer |
| `jobs[].credits` | object |
| `jobs[].credits.charged` | integer |
| `jobs[].credits.refunded` | integer |
| `jobs[].notify_webhook` | object |
| `jobs[].notify_webhook.endpoint_id` | string \| null |
| `jobs[].notify_webhook.status` | string |
| `jobs[].notify_webhook.event_type` | string \| null |
| `jobs[].notify_webhook.deliveries` | integer |
| `jobs[].links` | object |
| `jobs[].links.self` | string |
| `jobs[].links.results` | string |
| `jobs[].links.cancel` | string \| null |
| `limit` | integer |
| `has_more` | boolean |
| `next_cursor` | string \| null |

#### 예제 요청

```bash
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/jobs?limit=25&cursor=example&kind=batch"
```

```javascript
const response = await fetch("https://domscan.net/v1/jobs?limit=25&cursor=example&kind=batch", {
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY },
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.get(
    "https://domscan.net/v1/jobs?limit=25&cursor=example&kind=batch",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
)
print(response.json())
```

```go
package main

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://domscan.net/v1/jobs?limit=25&cursor=example&kind=batch", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/jobs?limit=25&cursor=example&kind=batch")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")

#### 예제 응답

```json
{
  "jobs": [
    {
      "id": "example-id",
      "kind": "batch",
      "status": "queued",
      "native_status": "queued",
      "created_at": "2026-08-27T12:00:00Z",
      "updated_at": "2026-08-27T12:00:00Z",
      "started_at": "2026-08-27T12:00:00Z",
      "completed_at": "2026-08-27T12:00:00Z",
      "results_expires_at": "2026-08-27T12:00:00Z",
      "progress": {
        "total": 1,
        "done": 1,
        "succeeded": 1,
        "failed": 1,
        "cancelled": 1
      },
      "credits": {
        "charged": 1,
        "refunded": 1
      },
      "notify_webhook": {
        "endpoint_id": "example",
        "status": "waiting",
        "event_type": "job.completed",
        "deliveries": 1
      },
      "links": {
        "self": "https://example.com",
        "results": "https://example.com",
        "cancel": "https://example.com"
      }
    }
  ],
  "limit": 1,
  "has_more": false,
  "next_cursor": "example"
}
```

#### HTTP 상태 코드

- `200` 성공
- `400` 잘못된 요청
- `401` 인증되지 않음
- `429` 요청 과다

## GET `/v1/jobs/:job_id`

작업: `getJob`
크레딧 및 인증: 무료
인증 필요

GET /v1/jobs/:job_id 크레딧: 0

#### 쿼리 매개변수

| 매개변수 | 유형 | 필수 |
| --- | --- | --- |
| job_id | string | 필수 |

#### 응답 필드

| 필드 | 유형 |
| --- | --- |
| `job` | object |
| `job.id` | string |
| `job.kind` | string |
| `job.status` | string |
| `job.native_status` | string |
| `job.created_at` | string \| null |
| `job.updated_at` | string \| null |
| `job.started_at` | string \| null |
| `job.completed_at` | string \| null |
| `job.results_expires_at` | string \| null |
| `job.progress` | object |
| `job.progress.total` | integer |
| `job.progress.done` | integer |
| `job.progress.succeeded` | integer |
| `job.progress.failed` | integer |
| `job.progress.cancelled` | integer |
| `job.credits` | object |
| `job.credits.charged` | integer |
| `job.credits.refunded` | integer |
| `job.notify_webhook` | object |
| `job.notify_webhook.endpoint_id` | string \| null |
| `job.notify_webhook.status` | string |
| `job.notify_webhook.event_type` | string \| null |
| `job.notify_webhook.deliveries` | integer |
| `job.links` | object |
| `job.links.self` | string |
| `job.links.results` | string |
| `job.links.cancel` | string \| null |

#### 예제 요청

```bash
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/jobs/string"
```

```javascript
const response = await fetch("https://domscan.net/v1/jobs/string", {
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY },
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.get(
    "https://domscan.net/v1/jobs/string",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
)
print(response.json())
```

```go
package main

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://domscan.net/v1/jobs/string", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/jobs/string")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")

#### 예제 응답

```json
{
  "job": {
    "id": "example-id",
    "kind": "batch",
    "status": "queued",
    "native_status": "queued",
    "created_at": "2026-08-27T12:00:00Z",
    "updated_at": "2026-08-27T12:00:00Z",
    "started_at": "2026-08-27T12:00:00Z",
    "completed_at": "2026-08-27T12:00:00Z",
    "results_expires_at": "2026-08-27T12:00:00Z",
    "progress": {
      "total": 1,
      "done": 1,
      "succeeded": 1,
      "failed": 1,
      "cancelled": 1
    },
    "credits": {
      "charged": 1,
      "refunded": 1
    },
    "notify_webhook": {
      "endpoint_id": "example",
      "status": "waiting",
      "event_type": "job.completed",
      "deliveries": 1
    },
    "links": {
      "self": "https://example.com",
      "results": "https://example.com",
      "cancel": "https://example.com"
    }
  }
}
```

#### HTTP 상태 코드

- `200` 성공
- `401` 인증되지 않음
- `404` 찾을 수 없음
- `429` 요청 과다

## GET `/v1/jobs/:job_id/results`

작업: `getJobResults`
크레딧 및 인증: 무료
인증 필요

GET /v1/jobs/:job_id/results 크레딧: 0

#### 쿼리 매개변수

| 매개변수 | 유형 | 필수 |
| --- | --- | --- |
| job_id | string | 필수 |
| limit | integer 기본값 `25` | 선택 사항 |
| cursor | string | 선택 사항 |

#### 응답 필드

| 필드 | 유형 |
| --- | --- |
| `job` | object |
| `job.id` | string |
| `job.kind` | string |
| `job.status` | string |
| `job.native_status` | string |
| `job.created_at` | string \| null |
| `job.updated_at` | string \| null |
| `job.started_at` | string \| null |
| `job.completed_at` | string \| null |
| `job.results_expires_at` | string \| null |
| `job.progress` | object |
| `job.progress.total` | integer |
| `job.progress.done` | integer |
| `job.progress.succeeded` | integer |
| `job.progress.failed` | integer |
| `job.progress.cancelled` | integer |
| `job.credits` | object |
| `job.credits.charged` | integer |
| `job.credits.refunded` | integer |
| `job.notify_webhook` | object |
| `job.notify_webhook.endpoint_id` | string \| null |
| `job.notify_webhook.status` | string |
| `job.notify_webhook.event_type` | string \| null |
| `job.notify_webhook.deliveries` | integer |
| `job.links` | object |
| `job.links.self` | string |
| `job.links.results` | string |
| `job.links.cancel` | string \| null |
| `results[]` | object[] |
| `results[]` | object |
| `results[].index` | integer |
| `results[].status` | string |
| `results[].reference` | string \| null |
| `results[].input` | unknown |
| `results[].data` | object \| null |
| `results[].error` | object |
| `results[].error.code` | string |
| `results[].error.message` | string |
| `results[].error.retryable` | boolean |
| `results[].credits` | object |
| `results[].credits.charged` | integer |
| `results[].credits.refunded` | integer |
| `limit` | integer |
| `has_more` | boolean |
| `next_cursor` | string \| null |

#### 예제 요청

```bash
curl -H "X-API-Key: $DOMSCAN_API_KEY" "https://domscan.net/v1/jobs/string/results?limit=25&cursor=example"
```

```javascript
const response = await fetch("https://domscan.net/v1/jobs/string/results?limit=25&cursor=example", {
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY },
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.get(
    "https://domscan.net/v1/jobs/string/results?limit=25&cursor=example",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
)
print(response.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://domscan.net/v1/jobs/string/results?limit=25&cursor=example", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/jobs/string/results?limit=25&cursor=example")
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")

#### 예제 응답

```json
{
  "job": {
    "id": "example-id",
    "kind": "batch",
    "status": "queued",
    "native_status": "queued",
    "created_at": "2026-08-27T12:00:00Z",
    "updated_at": "2026-08-27T12:00:00Z",
    "started_at": "2026-08-27T12:00:00Z",
    "completed_at": "2026-08-27T12:00:00Z",
    "results_expires_at": "2026-08-27T12:00:00Z",
    "progress": {
      "total": 1,
      "done": 1,
      "succeeded": 1,
      "failed": 1,
      "cancelled": 1
    },
    "credits": {
      "charged": 1,
      "refunded": 1
    },
    "notify_webhook": {
      "endpoint_id": "example",
      "status": "waiting",
      "event_type": "job.completed",
      "deliveries": 1
    },
    "links": {
      "self": "https://example.com",
      "results": "https://example.com",
      "cancel": "https://example.com"
    }
  },
  "results": [
    {
      "index": 1,
      "status": "pending",
      "reference": "example",
      "input": "example",
      "data": {},
      "error": {
        "code": "example",
        "message": "Request completed",
        "retryable": false
      },
      "credits": {
        "charged": 1,
        "refunded": 1
      }
    }
  ],
  "limit": 1,
  "has_more": false,
  "next_cursor": "example"
}
```

#### HTTP 상태 코드

- `200` 성공
- `400` 잘못된 요청
- `401` 인증되지 않음
- `404` 찾을 수 없음
- `410` HTTP 410
- `429` 요청 과다

## POST `/v1/jobs/:job_id/cancel`

작업: `cancelJob`
크레딧 및 인증: 무료
인증 필요

POST /v1/jobs/:job_id/cancel 크레딧: 0

#### 쿼리 매개변수

| 매개변수 | 유형 | 필수 |
| --- | --- | --- |
| job_id | string | 필수 |

#### 응답 필드

| 필드 | 유형 |
| --- | --- |
| `job` | object |
| `job.id` | string |
| `job.kind` | string |
| `job.status` | string |
| `job.native_status` | string |
| `job.created_at` | string \| null |
| `job.updated_at` | string \| null |
| `job.started_at` | string \| null |
| `job.completed_at` | string \| null |
| `job.results_expires_at` | string \| null |
| `job.progress` | object |
| `job.progress.total` | integer |
| `job.progress.done` | integer |
| `job.progress.succeeded` | integer |
| `job.progress.failed` | integer |
| `job.progress.cancelled` | integer |
| `job.credits` | object |
| `job.credits.charged` | integer |
| `job.credits.refunded` | integer |
| `job.notify_webhook` | object |
| `job.notify_webhook.endpoint_id` | string \| null |
| `job.notify_webhook.status` | string |
| `job.notify_webhook.event_type` | string \| null |
| `job.notify_webhook.deliveries` | integer |
| `job.links` | object |
| `job.links.self` | string |
| `job.links.results` | string |
| `job.links.cancel` | string \| null |
| `cancellation` | string |

#### 예제 요청

```bash
curl -X POST "https://domscan.net/v1/jobs/string/cancel" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{}'
```

```javascript
const response = await fetch("https://domscan.net/v1/jobs/string/cancel", {
  method: "POST",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.post(
    "https://domscan.net/v1/jobs/string/cancel",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={},
)
print(response.json())
```

```go
package main

func main() {
	body := strings.NewReader(`{}`)
	req, err := http.NewRequest(http.MethodPost, "https://domscan.net/v1/jobs/string/cancel", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/jobs/string/cancel")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({})

#### 예제 응답

```json
{
  "job": {
    "id": "example-id",
    "kind": "batch",
    "status": "queued",
    "native_status": "queued",
    "created_at": "2026-08-27T12:00:00Z",
    "updated_at": "2026-08-27T12:00:00Z",
    "started_at": "2026-08-27T12:00:00Z",
    "completed_at": "2026-08-27T12:00:00Z",
    "results_expires_at": "2026-08-27T12:00:00Z",
    "progress": {
      "total": 1,
      "done": 1,
      "succeeded": 1,
      "failed": 1,
      "cancelled": 1
    },
    "credits": {
      "charged": 1,
      "refunded": 1
    },
    "notify_webhook": {
      "endpoint_id": "example",
      "status": "waiting",
      "event_type": "job.completed",
      "deliveries": 1
    },
    "links": {
      "self": "https://example.com",
      "results": "https://example.com",
      "cancel": "https://example.com"
    }
  },
  "cancellation": "accepted"
}
```

#### HTTP 상태 코드

- `200` 성공
- `202` 수락됨
- `401` 인증되지 않음
- `404` 찾을 수 없음
- `409` HTTP 409
- `429` 요청 과다

## POST `/v1/estimate`

작업: `estimateRequestCost`
크레딧 및 인증: 무료
인증 필요

POST /v1/estimate 크레딧: 0

#### 본문 매개변수

| 매개변수 | 유형 | 필수 |
| --- | --- | --- |
| method | string 허용된 값 `GET`, `POST`, `PUT`, `PATCH`, `DELETE` | 필수 |
| path | string | 필수 |
| query | object | 선택 사항 |
| body | unknown | 선택 사항 |

#### 응답 필드

| 필드 | 유형 |
| --- | --- |
| `credits` | integer |
| `breakdown[]` | object[] |
| `breakdown[]` | object |
| `breakdown[].component` | string |
| `breakdown[].quantity` | integer |
| `breakdown[].unit_credits` | number |
| `breakdown[].credits` | integer |
| `notes[]` | string[] |
| `maximum` | boolean |
| `rejected` | boolean |
| `billing_model` | string |
| `endpoint` | object |
| `endpoint.method` | string |
| `endpoint.path` | string |
| `dry_run` | boolean |

#### 예제 요청

```bash
curl -X POST "https://domscan.net/v1/estimate" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{
  "method": "POST",
  "path": "/v1/value/bulk",
  "body": {
    "domains": [
      "example.com",
      "example.org",
      "example.net"
    ]
  }
}'
```

```javascript
const response = await fetch("https://domscan.net/v1/estimate", {
  method: "POST",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "method": "POST",
    "path": "/v1/value/bulk",
    "body": {
      "domains": [
        "example.com",
        "example.org",
        "example.net"
      ]
    }
  }),
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.post(
    "https://domscan.net/v1/estimate",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={
        "method": "POST",
        "path": "/v1/value/bulk",
        "body": {
            "domains": [
                "example.com",
                "example.org",
                "example.net",
            ],
        },
    },
)
print(response.json())
```

```go
package main

func main() {
	body := strings.NewReader(`{
	  "method": "POST",
	  "path": "/v1/value/bulk",
	  "body": {
	    "domains": [
	      "example.com",
	      "example.org",
	      "example.net"
	    ]
	  }
	}`)
	req, err := http.NewRequest(http.MethodPost, "https://domscan.net/v1/estimate", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/estimate")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "method" => "POST",
  "path" => "/v1/value/bulk",
  "body" => {
    "domains" => [
      "example.com",
      "example.org",
      "example.net"
    ]
  }
})

#### 예제 응답

```json
{
  "credits": 6,
  "breakdown": [
    {
      "component": "items",
      "quantity": 3,
      "unit_credits": 2,
      "credits": 6
    }
  ],
  "notes": [
    "Requests rejected with a 4xx status or failing with a 5xx status are refunded automatically."
  ],
  "maximum": false,
  "rejected": false,
  "endpoint": {
    "method": "POST",
    "path": "/v1/value/bulk"
  },
  "billing_model": "per_item"
}
```

#### HTTP 상태 코드

- `200` 성공
- `400` 잘못된 요청
- `401` 인증되지 않음
- `429` 요청 과다

## POST `/v1/feedback`

작업: `sendFeedback`
크레딧 및 인증: 무료
인증 필요

POST /v1/feedback 크레딧: 0

#### 본문 매개변수

| 매개변수 | 유형 | 필수 |
| --- | --- | --- |
| message | string | 필수 |
| category | string 허용된 값 `bug`, `feature_request`, `data_quality`, `docs`, `praise`, `other` 기본값 `other` | 선택 사항 |
| tool | string | 선택 사항 |

#### 응답 필드

| 필드 | 유형 |
| --- | --- |
| `received` | boolean |
| `feedback_id` | string |
| `category` | string |

#### 예제 요청

```bash
curl -X POST "https://domscan.net/v1/feedback" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOMSCAN_API_KEY" \
  -d '{
  "message": "WHOIS for example.io returns no registrar, but the registry shows one.",
  "category": "data_quality",
  "tool": "/v1/whois"
}'
```

```javascript
const response = await fetch("https://domscan.net/v1/feedback", {
  method: "POST",
  headers: { "X-API-Key": process.env.DOMSCAN_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "message": "WHOIS for example.io returns no registrar, but the registry shows one.",
    "category": "data_quality",
    "tool": "/v1/whois"
  }),
});
const data = await response.json();
console.log(data);
```

```python
import os
import requests

response = requests.post(
    "https://domscan.net/v1/feedback",
    headers={"X-API-Key": os.environ["DOMSCAN_API_KEY"]},
    json={
        "message": "WHOIS for example.io returns no registrar, but the registry shows one.",
        "category": "data_quality",
        "tool": "/v1/whois",
    },
)
print(response.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
	  "message": "WHOIS for example.io returns no registrar, but the registry shows one.",
	  "category": "data_quality",
	  "tool": "/v1/whois"
	}`)
	req, err := http.NewRequest(http.MethodPost, "https://domscan.net/v1/feedback", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("DOMSCAN_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(resp.Status, string(data))
}
```

```ruby
require "json"
require "net/http"

uri = URI("https://domscan.net/v1/feedback")
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = ENV.fetch("DOMSCAN_API_KEY")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "message" => "WHOIS for example.io returns no registrar, but the registry shows one.",
  "category" => "data_quality",
  "tool" => "/v1/whois"
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
puts JSON.pretty_generate(JSON.parse(response.body))
```

#### 예제 응답

```json
{
  "received": true,
  "feedback_id": "fbk_3f2c9a1b7d8e4f60a1b2c3d4e5f60718",
  "category": "data_quality"
}
```

#### HTTP 상태 코드

- `200` 성공
- `400` 잘못된 요청
- `401` 인증되지 않음
- `429` 요청 과다

## 레퍼런스 리소스

[OpenAPI 3.0](https://domscan.net/v1/openapi.json)
[Postman](https://domscan.net/v1/postman.json)
[MCP](https://domscan.net/ko/mcp-domain-checker)
