Overview

Validate up to 100 URLs in a single operation by uploading a CSV file. Each URL is individually validated and results are aggregated into a comprehensive report with per-URL and site-wide metrics.

How It Works

1. User uploads a CSV file (max 2MB) with one URL per row
2. ValidGraph queues all URLs for validation
3. Each URL is processed individually
4. Results are aggregated with overall statistics
5. Individual and combined reports are available

Tier Availability

| Tier | Available | Max URLs per CSV |
|——|———–|—————–|
| Free | No | — |
| Pro | Yes | 100 |
| Agency | Yes | 100 |
| Enterprise | Yes | 100 |

API Reference

POST /api/v1/bulk

Request: multipart/form-data with CSV file attachment.

Related Features

– URL Validation: Individual URL validation
– Export CSV/PDF: Export validation results
– Site-Wide Score: Aggregated site health metrics

Quick Start: Validate 100 URLs in One Upload

Step 1: Prepare your CSV file (max 2MB, max 100 rows)

data_url,schema_url
https://example.com/article-1,
https://example.com/article-2,
https://example.com/product-page,
https://example.com/faq,
https://example.com/recipe

Optional schema_url column specifies custom schema definitions (leave blank for standard validation).

Step 2: Upload via dashboard or API

curl -X POST https://api.validgraph.io/wp-json/validgraph/v1/bulk 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -F "[email protected]"

Step 3: Monitor progress — Validation runs asynchronously; dashboard shows per-URL results as they complete

Step 4: Export results — Download aggregated report with per-URL scores and site-wide metrics

Technical Details

CSV Format Specification

Minimum format:

data_url
https://example.com/page-1
https://example.com/page-2

Full format with optional columns:

data_url,schema_url
https://example.com/article,https://custom-schema.example.com/article-v2
https://example.com/product,
https://example.com/faq,https://custom-schema.example.com/faq-extended

Column headers are required. data_url is mandatory; schema_url is optional.

Request/Response

Request (multipart/form-data):

POST /wp-json/validgraph/v1/bulk
Content-Type: multipart/form-data

file: 

Response (202 Accepted):

{
  "success": true,
  "data": {
    "batch_id": "batch_xyz789",
    "urls_queued": 5,
    "max_urls": 100,
    "file_size_bytes": 245,
    "estimated_completion": "2024-03-22T14:35:00Z",
    "status_url": "/wp-json/validgraph/v1/bulk/batch_xyz789/status"
  }
}

Status Check (GET /wp-json/validgraph/v1/bulk/batch_xyz789/status):

{
  "batch_id": "batch_xyz789",
  "total_urls": 5,
  "completed": 3,
  "failed": 0,
  "pending": 2,
  "results": [
    {
      "url": "https://example.com/article-1",
      "validation_id": "val_abc123",
      "types": ["Article"],
      "score": 82,
      "errors": 0,
      "warnings": 1,
      "status": "completed"
    },
    {
      "url": "https://example.com/article-2",
      "validation_id": "val_abc124",
      "types": ["Article"],
      "score": 78,
      "errors": 1,
      "warnings": 2,
      "status": "completed"
    },
    {
      "url": "https://example.com/product",
      "status": "in_progress"
    }
  ],
  "aggregate_metrics": {
    "average_score": 80,
    "total_errors": 1,
    "total_warnings": 3,
    "schema_type_distribution": {
      "Article": 2,
      "Product": 1
    }
  }
}

Aggregate Results Example

Once all URLs complete, you can retrieve final aggregated results:

{
  "batch_id": "batch_xyz789",
  "total_urls": 5,
  "completed": 5,
  "failed": 0,
  "average_score": 79.4,
  "total_errors": 2,
  "total_warnings": 5,
  "score_distribution": {
    "90-100": 1,
    "80-89": 2,
    "70-79": 1,
    "60-69": 1,
    "<60": 0
  },
  "schema_types_found": {
    "Article": 3,
    "Product": 1,
    "FAQPage": 1
  },
  "most_common_warning": "image property missing (4 occurrences)",
  "export_formats": {
    "csv": "/downloads/batch_xyz789_results.csv",
    "pdf": "/downloads/batch_xyz789_results.pdf"
  }
}

Processing Details

– Queuing: URLs are validated sequentially to respect rate limits
– Timeout: Individual URL validations timeout after 30 seconds
– Retry: Failed validations are retried once automatically
– Rate limits: Bulk validation respects tier-specific monthly quotas
– Asynchronous: Response returns immediately (202 Accepted); results available via status endpoint

References

– CSV Format Standard (RFC 4180): https://tools.ietf.org/html/rfc4180
– URL Validation API: See URL Validation documentation
– Bulk Processing Best Practices: https://example.com/docs/bulk-processing
– Schema.org Supported Types: https://schema.org/docs/documents.html