Create Top Sources Task

Create Top Sources Task#

Retrieve top traffic sources ranked by session count, bandwidth usage, or other metrics.

✅ All code examples tested: Verified against FortiAnalyzer v7.4.8, v7.6.4, v8.0.0.

Overview#

This endpoint retrieves FortiView top sources data - useful for:

  • Identifying bandwidth-heavy users and devices

  • Network capacity planning and optimization

  • Monitoring user activity patterns

  • Security analysis of unusual traffic sources

  • Compliance reporting on network usage

  • Troubleshooting network performance issues

This endpoint uses the two-step asynchronous pattern. See the workflow below for complete details.

Endpoint Details#

Method: POST URL: /jsonrpc API Path (Step 1): /fortiview/adom/{adom}/top-sources/run API Path (Step 2): /fortiview/adom/{adom}/top-sources/{tid} ADOM Support: Yes Requires Authentication: Yes Minimum Version: 7.4.0

Prerequisites#

  • Active session or valid API key

  • Read access to FortiView data in specified ADOM

  • FortiView feature enabled on FortiAnalyzer

Two-Step Workflow#

Step 1: Submit Task#

Submit the top sources query and receive a Task ID (TID).

Step 2: Fetch Results#

Poll using the TID until complete, then retrieve the top sources data.

Step 1: Submit Top Sources Query#

Parameters#

Parameter

Type

Required

Default

Description

adom

string

Yes

-

ADOM name (e.g., “root”)

apiver

integer

No

3

API version

device

array

Yes

-

Device filter specification

filter

string

No

""

Additional filter expression

limit

integer

No

10

Number of top sources to return

sort-by

array

Yes

-

Sorting specification

time-range

object

Yes

-

Time range for data

case-sensitive

boolean

No

false

Filter case sensitivity

Device Filter#

Parameter

Type

Required

Description

└─ devid

string

Yes

Device ID or “All_Devices”

Sort Configuration#

Parameter

Type

Description

└─ field

string

Field to sort by: sessions, bytes, bandwidth

└─ order

string

Sort order: asc or desc

Time Range Format#

Parameter

Type

Required

Description

└─ start

string

Yes

Start time: “YYYY-MM-DD HH:MM:SS”

└─ end

string

Yes

End time: “YYYY-MM-DD HH:MM:SS”

Request Example#

{
    "method": "add",
    "params": [{
        "url": "/fortiview/adom/root/top-sources/run",
        "apiver": 3,
        "case-sensitive": false,
        "device": [{
            "devid": "All_Devices"
        }],
        "filter": "",
        "limit": 10,
        "sort-by": [{
            "field": "sessions",
            "order": "desc"
        }],
        "time-range": {
            "start": "2025-11-09 00:00:00",
            "end": "2025-11-09 23:59:59"
        }
    }],
    "session": "{{session_id}}",
    "id": 1
}

{
    "result": [{
        "data": {
            "tid": 12450
        },
        "status": {
            "code": 0,
            "message": "OK"
        }
    }]
}

Step 2: Fetch Results#

Parameters#

Parameter

Type

Required

Default

Description

adom

string

Yes

-

ADOM name (same as Step 1)

tid

integer

Yes

-

Task ID from Step 1

limit

integer

No

100

Results per page

offset

integer

No

0

Starting position for pagination

Request Example#

{
    "method": "get",
    "params": [{
        "url": "/fortiview/adom/root/top-sources/12450",
        "data": {
            "limit": 100,
            "offset": 0
        }
    }],
    "session": "{{session_id}}",
    "id": 2
}

{
    "result": [{
        "data": {
            "tid": 12450,
            "status": "done",
            "percentage": 100,
            "total": 10,
            "sources": [
                {
                    "srcip": "10.0.1.150",
                    "hostname": "LAPTOP-USER01",
                    "sessions": 4523,
                    "bytes": 2147483648,
                    "bandwidth": 45678901,
                    "country": "Reserved"
                },
                {
                    "srcip": "10.0.1.75",
                    "hostname": "DESKTOP-IT01",
                    "sessions": 3891,
                    "bytes": 1879048192,
                    "bandwidth": 39012345,
                    "country": "Reserved"
                },
                {
                    "srcip": "10.0.1.45",
                    "hostname": "SERVER-APP01",
                    "sessions": 3204,
                    "bytes": 1610612736,
                    "bandwidth": 33456789,
                    "country": "Reserved"
                }
            ]
        },
        "status": {
            "code": 0,
            "message": "OK"
        }
    }]
}

Response Fields#

Field

Type

Description

tid

integer

Task ID

status

string

Task status: “done”, “running”, “error”

percentage

integer

Completion percentage (0-100)

total

integer

Total number of sources returned

sources

array

Array of top source objects

Source Object Fields#

Field

Type

Description

srcip

string

Source IP address

hostname

string

Resolved hostname (if available)

sessions

integer

Number of sessions

bytes

integer

Total bytes transferred

bandwidth

integer

Bandwidth usage (bps)

country

string

GeoIP country

Complete Python Example#

import json
import requests
import urllib3
import time

urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

def get_top_sources(session_id, adom, time_range, limit=10, sort_field="sessions"):
    """
    Get top traffic sources for a time period

    Args:
        session_id: Active session ID
        adom: ADOM name
        time_range: Time range dict with 'start' and 'end'
        limit: Number of top sources to return (default: 10)
        sort_field: Field to sort by: sessions, bytes, bandwidth

    Returns:
        list: Top sources data
    """
    url = "https://faz.example.com/jsonrpc"

    # Step 1: Submit task
    payload = {
        "method": "add",
        "params": [{
            "url": f"/fortiview/adom/{adom}/top-sources/run",
            "apiver": 3,
            "case-sensitive": False,
            "device": [{"devid": "All_Devices"}],
            "filter": "",
            "limit": limit,
            "sort-by": [{
                "field": sort_field,
                "order": "desc"
            }],
            "time-range": time_range
        }],
        "session": session_id,
        "id": 1
    }

    response = requests.post(url, json=payload, verify=False)
    result = response.json()

    tid = result['result'][0]['data']['tid']
    print(f"✓ Task submitted. TID: {tid}")

    # Step 2: Poll for completion
    while True:
        poll_payload = {
            "method": "get",
            "params": [{
                "url": f"/fortiview/adom/{adom}/top-sources/{tid}"
            }],
            "session": session_id,
            "id": 2
        }

        response = requests.post(url, json=poll_payload, verify=False)
        data = response.json()['result'][0]['data']

        if data['status'] == 'done' and data['percentage'] == 100:
            print(f"✓ Found {data['total']} top sources")
            return data.get('sources', [])

        time.sleep(2)

# Example: Get top 10 sources by session count
sources = get_top_sources(
    session_id="your_session_id",
    adom="root",
    time_range={
        "start": "2025-11-09 00:00:00",
        "end": "2025-11-09 23:59:59"
    },
    limit=10,
    sort_field="sessions"
)

# Display results
print("\nTop Traffic Sources:")
for i, src in enumerate(sources, 1):
    print(f"{i}. {src['srcip']} ({src.get('hostname', 'Unknown')})")
    print(f"   Sessions: {src['sessions']:,}")
    print(f"   Bytes: {src['bytes']:,}")
    print(f"   Bandwidth: {src['bandwidth']:,} bps")
    print()

Use Cases#

Identify Bandwidth-Heavy Users#

# Get top 20 sources by bandwidth usage
sources = get_top_sources(
    session_id=session,
    adom="root",
    time_range={"last-n-hours": 24},
    limit=20,
    sort_field="bandwidth"
)

# Identify excessive bandwidth users
excessive_usage = [s for s in sources if s['bandwidth'] > 100000000]  # >100Mbps
for src in excessive_usage:
    print(f"High bandwidth: {src['srcip']} - {src['bandwidth']/1000000:.2f} Mbps")

Network Capacity Planning#

# Analyze traffic patterns for last 7 days
import datetime

end_time = datetime.datetime.now()
start_time = end_time - datetime.timedelta(days=7)

sources = get_top_sources(
    session_id=session,
    adom="root",
    time_range={
        "start": start_time.strftime("%Y-%m-%d %H:%M:%S"),
        "end": end_time.strftime("%Y-%m-%d %H:%M:%S")
    },
    limit=50,
    sort_field="bytes"
)

# Calculate total traffic
total_bytes = sum(s['bytes'] for s in sources)
print(f"Total traffic (7 days): {total_bytes/1024/1024/1024:.2f} GB")

# Show top 10 consumers
for i, src in enumerate(sources[:10], 1):
    percentage = (src['bytes'] / total_bytes) * 100
    print(f"{i}. {src['srcip']}: {src['bytes']/1024/1024/1024:.2f} GB ({percentage:.1f}%)")

Security Monitoring#

# Detect unusual traffic patterns
sources = get_top_sources(
    session_id=session,
    adom="root",
    time_range={"last-n-hours": 1},
    limit=100,
    sort_field="sessions"
)

# Flag sources with unusual session counts
threshold = 1000
suspicious = [s for s in sources if s['sessions'] > threshold]

if suspicious:
    print(f"⚠️ {len(suspicious)} sources with >1000 sessions/hour:")
    for src in suspicious:
        print(f"  {src['srcip']}: {src['sessions']:,} sessions")

Top Sources Report#

# Generate comprehensive top sources report
sources = get_top_sources(
    session_id=session,
    adom="root",
    time_range={
        "start": "2025-11-09 00:00:00",
        "end": "2025-11-09 23:59:59"
    },
    limit=25,
    sort_field="sessions"
)

# Format as report
print("=" * 80)
print("TOP TRAFFIC SOURCES REPORT")
print("=" * 80)
print(f"{'Rank':<6} {'IP Address':<16} {'Hostname':<20} {'Sessions':>10} {'Bandwidth':>12}")
print("-" * 80)

for i, src in enumerate(sources, 1):
    hostname = src.get('hostname', 'Unknown')[:20]
    bandwidth_mbps = src['bandwidth'] / 1000000
    print(f"{i:<6} {src['srcip']:<16} {hostname:<20} {src['sessions']:>10,} {bandwidth_mbps:>11.2f}M")

Error Handling#

{
    "result": [{
        "status": {
            "code": -3,
            "message": "Invalid task ID"
        }
    }]
}

Common causes:

  • Task ID has expired

  • Invalid TID value

  • FortiView data not available for time range

  • Insufficient permissions

Best Practices#

💡 Tip: Use appropriate time ranges - shorter ranges return faster results and reduce server load.

💡 Tip: Start with smaller limits (10-25) for quick overviews, increase to 100+ for comprehensive analysis.

⚠️ Warning: Tasks expire after a period of inactivity. Fetch results promptly after task completion.

💡 Tip: Sort by different fields (sessions, bytes, bandwidth) to get different perspectives on network usage.

On this page