logo
การพัฒนา
ภาพรวมพื้นที่นักพัฒนาพื้นที่ทำงานเอกสาร APIแนวปฏิบัติที่ดีบันทึกการเปลี่ยนแปลง
ค้นหา
ภาษาไทย
เอกสาร API / วิเคราะห์ API / การดึงการกระจายการใช้คะแนนขององค์กร
การดึงการกระจายการใช้เครดิตขององค์กร
อัปเดตล่าสุด：14 วันที่ผ่านมา

การดึงการกระจายการใช้เครดิตขององค์กร

สามารถดึงอันดับสัดส่วนของเครดิตหรือ token ขององค์กรตาม Agent / Workflow รวมถึงแนวโน้มรายวัน รายสัปดาห์ รายเดือน สามารถดูเฉพาะ Agent หรือเฉพาะ Workflow ก็ได้

หมายเหตุ: สามารถดึงข้อมูลได้สูงสุด 92 วัน; นับเฉพาะพื้นที่การพัฒนา ขอบเขตการสถิติตามที่ระบุใน "เกณฑ์การนับสถิติ" ด้านล่าง

วิธีการขอข้อมูล

GET

ที่อยู่การเรียกใช้

https://api-${endpoint}.gptbots.ai/v1/org/usage/distribution

การยืนยันการเรียกใช้

ใช้การรับรองความถูกต้อง Basic ของ DevKey / DevSecret ระดับบัญชี: Authorization: Basic ${BASIC_TOKEN} โดยที่ ${BASIC_TOKEN} เป็นรหัส Base64 ของ DevKey:DevSecret

  • บัญชีที่เรียกต้องเป็นสมาชิกขององค์กรที่สอดคล้องกับ org_id และมีสิทธิ์ "ดูการใช้" (Owner และผู้ดูแลระบบขององค์กรมีสิทธิ์โดยค่าเริ่มต้น)
  • กรุณาเรียกที่อยู่ของศูนย์ข้อมูลที่องค์กรตั้งอยู่ ${endpoint} ใช้ region ที่ได้จาก รายการตรวจสอบองค์กร (SG → sg, TH → th, JP → jp) การเรียกจากศูนย์ข้อมูลอื่นจะได้รับ "ไม่ใช่สมาชิกองค์กรนี้"

ความถี่ในการเรียกใช้

  • คีย์นักพัฒนาหนึ่งสามารถเรียก API นี้ได้สูงสุด 10 ครั้งต่อนาที
  • การเรียกแต่ละครั้งจะถูกนับรวมกับโควต้าต่อชั่วโมงของ "API ประเภทสถิติ" ขององค์กร และใช้ร่วมกับ API Key ของ Agent ที่เรียก API ประเภทสถิติ
  • ผลลัพธ์การค้นหาจะถูกเก็บในแคช 10 นาที แนะนำให้เรียกวันละครั้ง

คำขอ

ตัวอย่างคำขอ

curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/usage/distribution?org_id=${org_id}&start_time=1792425600000&end_time=1792684800000&agent_type=WORKFLOW&granularity=DAY' \ -H 'Authorization: Basic ${BASIC_TOKEN}'
                      
                      curl -X GET 'https://api-${endpoint}.gptbots.ai/v1/org/usage/distribution?org_id=${org_id}&start_time=1792425600000&end_time=1792684800000&agent_type=WORKFLOW&granularity=DAY' \
  -H 'Authorization: Basic ${BASIC_TOKEN}'
บล็อกโค้ดนี้ในหน้าต่างลอย

ส่วนหัวของคำขอ

ฟิลด์ ประเภท คำอธิบาย
Authorization Basic ${BASIC_TOKEN} ใช้ Basic Token หลังจากเข้ารหัส Base64 ของ DevKey:DevSecret

พารามิเตอร์ของคำขอ

ฟิลด์ ประเภท จำเป็น คำอธิบาย
org_id String ใช่ รหัสองค์กร
start_time Long ใช่ เวลาเริ่มต้นในรูปเวลามิลลิวินาที ขยายไปยังเวลา 0 นาฬิกาของวันตามเขตเวลาขององค์กร
end_time Long ใช่ เวลาสิ้นสุด (ไม่รวม) ในรูปเวลามิลลิวินาที ระยะเวลาไม่เกิน 92 วัน
metric String ไม่ CREDITS (เครดิต ค่าเริ่มต้น) หรือ TOKENS
granularity String ไม่ ความละเอียดของแนวโน้มตามเวลา: DAY (ค่าเริ่มต้น), WEEK (เริ่มวันจันทร์), MONTH
agent_type String ไม่ AGENT ดูเฉพาะ Agent, WORKFLOW ดูเฉพาะ Workflow; หากไม่ระบุ จัดอันดับทั้งสองประเภทพร้อมกัน
top_n Integer ไม่ จำนวนรายการที่เก็บในลำดับแนวโน้ม 1 ถึง 50 ค่าเริ่มต้น 50 รายการที่เหลือรวมเป็นบรรทัดเดียว OTHER

การตอบสนอง

ตัวอย่างการตอบสนอง

{ "code": 0, "message": "OK", "data": { "timezone": "+07:00", "data_since": "2026-10-15", "buckets": ["2026-10-16", "2026-10-17", "2026-10-18"], "total": 812.4411, "series": [ { "row_type": "ITEM", "agent_id": "65f0c2a1b4e8d93a1c7e5b2a", "name": "订单查询", "agent_type": "WORKFLOW", "total": 402.1200, "share": 49.49, "points": [130.5000, 141.0200, 130.6000] }, { "row_type": "OTHER", "agent_id": null, "name": null, "agent_type": null, "total": 410.3211, "share": 50.51, "points": [120.1000, 150.2000, 140.0211] } ], "ranking": [ { "row_type": "ITEM", "agent_id": "65f0c2a1b4e8d93a1c7e5b2a", "name": "订单查询", "agent_type": "WORKFLOW", "total": 402.1200, "share": 49.49 } ] } }
                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "timezone": "+07:00",
        "data_since": "2026-10-15",
        "buckets": ["2026-10-16", "2026-10-17", "2026-10-18"],
        "total": 812.4411,
        "series": [
            {
                "row_type": "ITEM",
                "agent_id": "65f0c2a1b4e8d93a1c7e5b2a",
                "name": "订单查询",
                "agent_type": "WORKFLOW",
                "total": 402.1200,
                "share": 49.49,
                "points": [130.5000, 141.0200, 130.6000]
            },
            {
                "row_type": "OTHER",
                "agent_id": null,
                "name": null,
                "agent_type": null,
                "total": 410.3211,
                "share": 50.51,
                "points": [120.1000, 150.2000, 140.0211]
            }
        ],
        "ranking": [
            {
                "row_type": "ITEM",
                "agent_id": "65f0c2a1b4e8d93a1c7e5b2a",
                "name": "订单查询",
                "agent_type": "WORKFLOW",
                "total": 402.1200,
                "share": 49.49
            }
        ]
    }
}
บล็อกโค้ดนี้ในหน้าต่างลอย

การตอบสนองสำเร็จ

ฟิลด์ ประเภท คำอธิบาย
timezone String เขตเวลาขององค์กร (ส่วนต่าง UTC เช่น +07:00)
data_since String วันที่เริ่มต้นของข้อมูลเครดิต (yyyy-MM-dd), ช่วงเวลาก่อนหน้านี้ไม่ครบถ้วน; หากยังไม่มีข้อมูลใด ๆ ให้เป็น null
buckets String[] วันที่เริ่มต้นของถังเวลา เรียงลำดับจากน้อยไปมาก: ตามวันเป็นวันปัจจุบัน, ตามสัปดาห์เป็นวันจันทร์ (yyyy-MM-dd), ตามเดือนเป็น yyyy-MM; points สอดคล้องกับลำดับนี้
total Number ยอดรวมในช่วงเวลา (เครดิตหรือโทเค็น ขึ้นอยู่กับ metric)
series Object[] แถวสำหรับแนวโน้ม top_n ลำดับจากยอดรวมสูงสุดไปต่ำสุด, แถวที่เหลือรวมเป็นหนึ่งแถว row_type = OTHER
ranking Object[] อันดับเต็ม สูงสุด 500 แถว, ส่วนที่เกินรวมเป็นแถวเดียว OTHER ไม่รวม points
series[].row_type / ranking[].row_type String ITEM ตัวแทน (Agent) หรือ Workflow; OTHER รายการรวม; UNATTRIBUTED การใช้จ่ายที่ไม่เกี่ยวข้องกับ Agent ใด ๆ (เช่น การเก็บใน Knowledge Base, การรู้จำเสียง), หากส่ง agent_type จะไม่ส่งแถวนี้กลับ
series[].agent_id / ranking[].agent_id String ID ของ Agent หรือ Workflow; OTHER / UNATTRIBUTED แถวเป็น null
series[].name / ranking[].name String ชื่อ; OTHER / UNATTRIBUTED แถวเป็น null
series[].agent_type / ranking[].agent_type String AGENT หรือ WORKFLOW; OTHER / UNATTRIBUTED พฤติกรรม null.
series[].total / ranking[].total Number จำนวนรวมของช่วง เก็บทศนิยม 4 หลัก.
series[].share / ranking[].share Number เปอร์เซ็นต์ของจำนวนรวมในช่วง 0 ถึง 100 เก็บทศนิยม 2 หลัก.
series[].points Number[] ค่าของแต่ละถังเวลา.

การตอบกลับล้มเหลว

ฟิลด์ ประเภท คำอธิบาย
code Integer รหัสข้อผิดพลาด.
message String รายละเอียดข้อผิดพลาด.

รหัสข้อผิดพลาด

รหัสสถานะ HTTP คือสามหลักแรกของรหัสข้อผิดพลาด เช่น 40000 ตรงกับ 400, 40100 ตรงกับ 401, 403132 ตรงกับ 403.

รหัสข้อผิดพลาด คำอธิบาย
40000 ข้อผิดพลาดของพารามิเตอร์ เช่น ขาดพารามิเตอร์ที่จำเป็น หรือค่าพารามิเตอร์ไม่ถูกต้อง.
40001 เรียกใช้งานบ่อยเกินไป: คีย์นักพัฒนานี้เกินขีดจำกัดสูงสุดต่อหนึ่งนาทีของ API นี้.
40008 เกินโควต้าต่อหนึ่งนาทีของแพ็กเกจองค์กรสำหรับ "API ประเภทสถิติ".
40010 API ปิดชั่วคราว กรุณาลองใหม่ภายหลัง.
40100 ไม่มีสิทธิ์: ขาดสิทธิ์การดูการใช้งาน.
40105 ไม่ใช่สมาชิกขององค์กรนี้ หรือเรียกใช้งานจากที่อยู่ของศูนย์ข้อมูลอื่น.
40324 DevKey หรือ DevSecret ผิดพลาด.
403132 ช่วงเวลาผิดพลาด: เวลาเริ่มต้นไม่ก่อนเวลาสิ้นสุด หรือเกินช่วงค้นหาสูงสุด.

ขอบเขตการสถิติ

  • ขอบเขตการสถิติ: นับเฉพาะพื้นที่พัฒนา รวมถึง API, หน้าแชร์, การฝังเว็บ, ส่วนประกอบฟอง, LiveDesk และช่องทางการสื่อสารและโทรศัพท์แบบเรียลไทม์ รวมถึง Workflow ของพื้นที่พัฒนา; ไม่รวมการใช้งานของพื้นที่ทำงาน (GWork) และไม่รวมการใช้งานของ Agent ที่เผยแพร่แล้วภายในพื้นที่ทำงาน ดังนั้นจำนวนรวมอาจต่ำกว่าช่วงเวลาเดียวกันในหน้า "องค์กร → การใช้งาน" ของคอนโซลเล็กน้อย
  • เครดิต: ทุกประเภทการใช้ (ยกเว้นเครดิตหมดอายุและการชำระค่าสมาชิก); การใช้ Workflow จะถูกบันทึกภายใต้ชื่อของ Workflow เอง
  • จุดเริ่มต้นของข้อมูล: มีตั้งแต่วันที่ฟีเจอร์เปิดตัว (data_since) และจะไม่เติมข้อมูลย้อนหลัง
  • ความถี่ในการอัปเดต: อัปเดตแบบเรียลไทม์