Monitoring & Automation · DomScan product

Asynchronous API batches API

Queue many supported API requests and collect their results without keeping a client connection open.

What you get

Queue many supported API requests and collect their results without keeping a client connection open.

AsynchronousRESTMCPSDK

Choose this product when

Who it is for

Use automation when the same decision must run across time, across a list, or across several products.

Choose this product when

Choose this to queue up to 100 supported GET requests and retrieve JSON or CSV results within the 24-hour retention window.

What you get

Queue many supported API requests and collect their results without keeping a client connection open.

Endpoints

See what each endpoint accepts and returns, its modes and its limits before you integrate.

POST /v1/batches View API reference
GET /v1/batches View API reference
GET /v1/batches/:job_id View API reference
GET /v1/batches/:job_id/results View API reference
DELETE /v1/batches/:job_id View API reference
GET /v1/jobs View API reference
GET /v1/jobs/:job_id View API reference
GET /v1/jobs/:job_id/results View API reference
POST /v1/jobs/:job_id/cancel View API reference
POST /v1/estimate View API reference
POST /v1/feedback View API reference

Credits and authentication

Free Authentication required. See the API reference for the exact cost, including any per-item pricing.

Example operation

Use documented operations to collect, assess, enrich, verify, compare, protect, or monitor public evidence.

POST /v1/batches Credits: 0

Body parameters

Parameter Type required
notify_webhook unknown optional
requests object[] required
webhook object optional

Response fields

Field Type
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

Example request

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"
  }
}'
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);
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())
package main

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

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")

	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))
}
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"
  }
})

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))

Example response

{
  "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 status codes

  • 200 OK
  • 202 Accepted
  • 400 Bad Request
  • 401 Unauthorized
  • 402 Payment Required
  • 409 HTTP 409
  • 429 Too Many Requests

Frequently asked questions

Where can I find the Asynchronous API batches request and response reference?

Use the API reference for Asynchronous API batches to review parameters, response fields, examples, status codes, and supported operation modes.

How should I interpret unknown or incomplete results from Asynchronous API batches?

Unknown or partial means we could not fully confirm the result. Keep the status, confidence, freshness and any limits in mind when you act on it.

How is Asynchronous API batches priced?

The price depends on the check and the mode you choose. The API reference shows the current credit cost, whether you need an API key, and any per-item pricing.

Used by people at these companies

InstantOutseerMongoDBRespondentSage Expense ManagementInstantlyD.R. HortonWhatConvertsAdobeLLM Pulse