> 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/ar/docs/products/batch-jobs

# API الخاص بـ دفعات API غير المتزامنة

ضع العديد من طلبات API المدعومة في قائمة انتظار واجمع نتائجها من دون إبقاء اتصال العميل مفتوحاً. استخدم هذا المرجع لاختيار نقطة النهاية المناسبة ومعرفة ما تعيده بالضبط.

[عرض صفحة المنتج](https://domscan.net/ar/async-batch-api)

## العمليات

POST `/v1/batches` [عرض مرجع API](https://domscan.net/ar/docs/products/batch-jobs#createApiBatch)

GET `/v1/batches` [عرض مرجع API](https://domscan.net/ar/docs/products/batch-jobs#listApiBatches)

GET `/v1/batches/:job_id` [عرض مرجع API](https://domscan.net/ar/docs/products/batch-jobs#getApiBatch)

GET `/v1/batches/:job_id/results` [عرض مرجع API](https://domscan.net/ar/docs/products/batch-jobs#getApiBatchResults)

DELETE `/v1/batches/:job_id` [عرض مرجع API](https://domscan.net/ar/docs/products/batch-jobs#cancelApiBatch)

GET `/v1/jobs` [عرض مرجع API](https://domscan.net/ar/docs/products/batch-jobs#listJobs)

GET `/v1/jobs/:job_id` [عرض مرجع API](https://domscan.net/ar/docs/products/batch-jobs#getJob)

GET `/v1/jobs/:job_id/results` [عرض مرجع API](https://domscan.net/ar/docs/products/batch-jobs#getJobResults)

POST `/v1/jobs/:job_id/cancel` [عرض مرجع API](https://domscan.net/ar/docs/products/batch-jobs#cancelJob)

POST `/v1/estimate` [عرض مرجع API](https://domscan.net/ar/docs/products/batch-jobs#estimateRequestCost)

POST `/v1/feedback` [عرض مرجع API](https://domscan.net/ar/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` OK
- `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` OK
- `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` OK
- `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` OK
- `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` OK
- `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` OK
- `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` OK
- `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` OK
- `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` OK
- `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` OK
- `400` طلب غير صالح
- `401` غير مصرح
- `429` طلبات كثيرة جداً

## موارد المرجع

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