# GET /v1/stats/subid

عرض الإحصاءات بحسب sub-id

مرات الظهور والإيراد وeCPM مجمّعة بحسب sub1 وsub2 وsub3، لمدة لا تتجاوز 90 يومًا؛ بصيغة JSON أو CSV. إيراد كل sub-id هو توزيع للإيراد الذي يعرضه /v1/stats لكل منطقة إعلانية ودولة بنسبة مرات الظهور، وليس قياسًا منفصلًا (`revenue_allocated` دائمًا true)؛ وتساوي الإجماليات إجماليات /v1/stats للنطاق والمرشحات نفسها. ترتّب الصفوف بحسب الإيراد؛ وتدمج الصفوف التي تتجاوز `limit` في صف واحد قيمة sub-id فيه `~other`. القيمة null لـ sub-id تعني أنه لم يرسل sub-id. تتطلب الصلاحية publisher:read (مفتاح API أو جلسة ويب). فئة حد المعدل: stats.

- الصلاحية المطلوبة: `publisher:read`
- حد المعدل: `stats` — 30 طلبًا لكل نافذة مدتها 60 ثانية لكل مفتاح API أو جلسة ويب

## المعاملات

| الاسم | الموضع | النوع | مطلوب |
|---|---|---|---|
| `from` | query | string | نعم |
| `to` | query | string | نعم |
| `group_by` | query | ("sub1" \| "sub2" \| "sub3")[] | لا |
| `site_id` | query | integer | لا |
| `zone_id` | query | integer | لا |
| `sub1` | query | string | لا |
| `sub2` | query | string | لا |
| `sub3` | query | string | لا |
| `limit` | query | integer | لا |
| `format` | query | "json" \| "csv" | لا |

## الاستجابة

```
{ count_basis?: "valid" | "legacy" | "mixed"; currency: "USD"; estimated_from: string | null; forecast_basis_version?: "forecast-basis-v1"; forecast_generation?: string; forecast_updated_at?: string | null; measurement_definition?: { complete: boolean; includes_direct: boolean; includes_legacy: boolean; tag_valid_after_ms: integer[] }; measurement_generation?: string; measurement_status?: "ok" | "stale" | "updating"; measurement_updated_at?: string | null; money_basis_version?: string; money_generation?: string; revenue_allocated: true; rows: { ecpm: string | null; pops: integer; revenue: string; status?: "estimated" | "reported" | "final" | "mixed"; sub1?: string | null; sub2?: string | null; sub3?: string | null }[]; totals: { ecpm: string | null; pops: integer; revenue: string; status?: "estimated" | "reported" | "final" | "mixed" }; truncated?: boolean; updated_at?: string | null }
```

## الأخطاء

تعيد المسارات الخاضعة لحد المعدل الترويسات `RateLimit-Limit` و`RateLimit-Remaining` و`RateLimit-Reset` (عدد الثواني حتى انتهاء النافذة)؛ وتحمل الاستجابة 429 أيضًا `Retry-After`. قد تغيب الترويسات أثناء عدم توفر المحدّد مؤقتًا (وتمرّر الطلبات حينئذ).

| الحالة | المعنى |
|---|---|
| 401 | مفتاح API مفقود أو غير صالح أو ملغى. |
| 403 | ينقص المفتاح الصلاحية المطلوبة، أو العملية غير مسموح بها لهذا الطرف. |
| 429 | تم تجاوز حد المعدل؛ انتظر `Retry-After` ثانية. |
| 400 | Default Response |
| 404 | Default Response |
| 503 | Default Response |

وثائق HTML: https://agimone.com/ar/developers/api/#get-subid-stats
API 2026-10
