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

# Get AI Articles Quota

> Calculate AI articles quota for one-time burst creation

Calculates how many AI articles the cron job should create. Uses a **one-time burst architecture** that creates all 1,000 articles on the first cron run after signup.

**Authentication:** Requires internal API key (`X-API-Key` header).

## How It Works

The system uses a **one-time burst** model:

1. **First cron run after signup**: Creates all 1,000 articles in one batch
2. **Subsequent runs**: Returns 0 quota (already completed for the week)

```
Cron (Job 4: Create AI Articles)
    │
    └── For each business:
        │
        ├── GET /ai-articles-quota?org_slug={business_id}
        │   └── Returns: 1000 articles (first run) or 0 (already done)
        │
        └── Create articles for each product (round-robin distribution)
```

<Note>
  **Products only** - AI articles are created for products, not the business
  entity itself. All articles are deployed to the business's AI site.
</Note>

## One-Time Burst Architecture

Unlike a daily distribution model, this architecture front-loads all content creation:

| Scenario                                | Quota Returned |
| --------------------------------------- | -------------- |
| First run of the week (no articles yet) | 1,000 articles |
| Any subsequent run (articles exist)     | 0 articles     |

This ensures new customers get their full content library immediately after signup.

## Product Distribution (Round-Robin)

The 1,000 articles are distributed across products using round-robin:

1. Products are ordered by `article_count` (ascending)
2. Products with fewest articles get priority
3. Articles are distributed evenly across all products

**Example with 50 products:**

* Each product gets 20 articles (1000 ÷ 50)
* Products with fewer existing articles are prioritized

**Example with 200 products:**

* Each product gets 5 articles (1000 ÷ 200)
* All products get coverage in a single burst

## Query Parameters

<ParamField query="org_slug" type="string" required>
  The organization slug (business\_id)
</ParamField>

## Response

<ResponseField name="org_slug" type="string">
  The organization slug
</ResponseField>

<ResponseField name="week_start" type="string">
  Start of current week (Monday) in YYYY-MM-DD format
</ResponseField>

<ResponseField name="week_end" type="string">
  End of current week (Sunday) in YYYY-MM-DD format
</ResponseField>

<ResponseField name="weekly_target" type="integer">
  Total weekly target (1000)
</ResponseField>

<ResponseField name="articles_this_week" type="integer">
  Articles already created this week
</ResponseField>

<ResponseField name="total_products" type="integer">
  Total number of products for this organization
</ResponseField>

<ResponseField name="products" type="array">
  Array of product quotas

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Product entity ID
    </ResponseField>

    <ResponseField name="name" type="string">
      Product name
    </ResponseField>

    <ResponseField name="daily_quota" type="integer">
      Articles to create for this product
    </ResponseField>

    <ResponseField name="total_articles" type="integer">
      Total articles already created for this product
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_daily_quota" type="integer">
  Total articles to create (1000 or 0)
</ResponseField>

<ResponseField name="architecture" type="string">
  Always "one-time-burst"
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message
</ResponseField>

<RequestExample>
  ```bash curl theme={null}
  curl "https://searchcompany-main.up.railway.app/api/cron/ai-articles-quota?org_slug=nike" \
    -H "X-API-Key: search-company"
  ```
</RequestExample>

<ResponseExample>
  ```json Response (First Run - Full Burst) theme={null}
  {
    "org_slug": "nike",
    "week_start": "2026-01-06",
    "week_end": "2026-01-12",
    "weekly_target": 1000,
    "articles_this_week": 0,
    "articles_remaining": 1000,
    "total_products": 50,
    "products": [
      {
        "id": "uuid-1",
        "name": "Air Max",
        "daily_quota": 20,
        "total_articles": 0
      },
      {
        "id": "uuid-2",
        "name": "Air Force 1",
        "daily_quota": 20,
        "total_articles": 0
      }
    ],
    "total_daily_quota": 1000,
    "message": "First run - creating full weekly burst",
    "architecture": "one-time-burst"
  }
  ```

  ```json Response (Already Completed) theme={null}
  {
    "org_slug": "nike",
    "week_start": "2026-01-06",
    "week_end": "2026-01-12",
    "weekly_target": 1000,
    "articles_this_week": 1000,
    "products": [],
    "total_daily_quota": 0,
    "message": "Weekly burst already completed",
    "architecture": "one-time-burst"
  }
  ```

  ```json Response (No Products) theme={null}
  {
    "org_slug": "acme-corp",
    "week_start": "2026-01-06",
    "week_end": "2026-01-12",
    "weekly_target": 1000,
    "articles_this_week": 0,
    "products": [],
    "total_daily_quota": 0,
    "message": "No products found - add products to generate articles"
  }
  ```
</ResponseExample>

## Integration with Cron

The cron job uses this quota API to determine article creation:

1. Calls this API to get the quota
2. If `total_daily_quota > 0`: Creates articles for each product in parallel
3. All articles are deployed to the business's AI site
4. Subsequent cron runs return 0 quota until next week

This one-time burst approach means:

* **New customers**: Get all 1,000 articles immediately
* **Existing customers**: No redundant work on subsequent runs
* **Weekly reset**: Quota resets each Monday for ongoing content freshness