/Details Endpont - `count` optionnal query parameter seems broken

[Nicolas-Pellletier]

Hello @LegendEvent,

Thanks for taking the time to developped this tool and sharing it with the community. I'm encounter an issue when requesting the Details Endpoint , in order to get Detailed information about specific entities.

The count optional parameter when requesting the /Details endpoint seems broken.

Here is below my code:

    connection_events_bis = client.details.get(pbid=pbid, eventtype="connection", count=100)
    notice_events = client.details.get(pbid=pbid, eventtype="notice", count=800)
    all_event_types = client.details.get(pbid=pbid, count=100)
    print(f"Il y a un total de {len(connection_events)} connexions")
    print(f"Il y a un total de {len(connection_events_bis)} connexions bis")
    print(f"Il y a un total de {len(notice_events)} notice events")
    print(f"Il y a un total de {len(all_event_types)} events")

Here is the below result:

Il y a un total de 200 connexions
Il y a un total de 0 connexions bis
Il y a un total de 800 notice events
Il y a un total de 0 events

When i use the count parameter with notice eventTypes it looks fine, but then if i don't specify any eventTypes to return or i specify only connection eventTypes to return, i get no result.

Regards

[LegendEvent]

Validation Attempt

I tested this issue on a Darktrace instance with SDK v0.8.55.

Test Results

Test	Parameters	Result
1	eventtype='connection' WITHOUT count	200 connections ✓
2	eventtype='connection' WITH count=100	100 connections ✓
3	eventtype='notice' WITH count=800	1 notice ✓
4	NO eventtype WITH count=100	100 items ✓

Conclusion

Unable to reproduce the issue. The count parameter works correctly in all tested scenarios.

Could you provide:

1. Your SDK version: pip show darktrace-sdk
2. Your Darktrace instance version
3. A debug output with debug=True enabled

This will help identify if the issue is version-specific or related to specific data on your instance.

[LegendEvent]

Validation Update

I tested this issue across multiple SDK versions (v0.8.1 through v0.8.55) and was unable to reproduce the bug.

Test Results (SDK v0.8.55, Darktrace v6.3.18)

Test	Parameters	Result
1	`eventtype='connection'` without count	200 items ✓
2	`eventtype='connection'` with count=100	100 items ✓
3	`eventtype='notice'` with count=800	1 item ✓
4	no eventtype with count=100	100 items ✓

The `count` parameter works correctly in all scenarios on our instance.

Debug Script

Please run this with your credentials and share the output:

from darktrace import DarktraceClient

client = DarktraceClient(
    host="https://your-darktrace-instance",
    public_token="YOUR_PUBLIC_TOKEN",
    private_token="YOUR_PRIVATE_TOKEN",
    debug=True
)

pbid = 12345  # Use your pbid - try multiple different pbids if possible

for name, kwargs in [
    ("TEST 1: connection without count", {"pbid": pbid, "eventtype": "connection"}),
    (\"TEST 2: connection with count=100", {"pbid": pbid, "eventtype": "connection", "count": 100}),
    (\"TEST 3: notice with count=800", {"pbid": pbid, "eventtype": "notice", "count": 800}),
    (\"TEST 4: no eventtype with count=100", {"pbid": pbid, "count": 100}),
]:
    print(f"\n{name}")
    result = client.details.get(**kwargs)
    print(f"  Type: {type(result).__name__}")
    print(f"  len(): {len(result)}")

from darktrace import __version__
print(f"\nSDK version: {__version__}")
status = client.status.get()
print(f"Darktrace version: {status.get('version', 'unknown')}")

Info Needed

1. SDK version: pip show darktrace-sdk
2. Darktrace version (from /status endpoint)
3. Output from debug script above
4. Try multiple different pbids - the issue might be specific to certain model breaches

This will help determine if the issue is related to specific data, your Darktrace version, or something else.

[Nicolas-Pellletier]

Hello @LegendEvent,

First of all thanks a lot for taking the time to develop this response and the debug script.
Here is the info retrieved based on the script execution:

1. SDK version: 0.8.53
2. Darktrace version: 6.3.18 (465fe1b8)

API Token used and Model Alert

I didn't use Global API Token but User based token with API Access.
As showned below, i've tested several bpid linked to different Model Alerts:

pbid = 27439 # Anomalous NTLM Brute Force
pbid = 28294 # Possible Denial of Service Activity n°1
pbid = 25323 # Possible Denial of Service Activity n°2
pbid = 28384 # SMB Drive Write
pbid = 27440 # SMB Session Brute Force (Non-Admin)

Comment: Take approximately 10 seconds to execute first time i execute the script (Like it was due to the fact)
Then less than 1 second

Test Results (SDK version: v0.8.53, Darktrace v6.3.18)

Test: pbid = 27439 | Anomalous NTLM Brute Force

Test	Parameters	Result
1	eventtype='connection' without count	200 items ✓
2	eventtype='connection' with count=100	0 item✖
3	eventtype='notice' with count=800	0 items ✖
4	no eventtype with count=100	0 items✖

Test: pbid = 28294 | Possible Denial of Service Activity n°1

Comment: Take about 10 seconds first time execution (then almost instantanly)

Test	Parameters	Result
1	eventtype='connection' without count	200 items ✓
2	eventtype='connection' with count=100	0 item✖
3	eventtype='notice' with count=800	2 items ✓
4	no eventtype with count=100	0 items✖

Test: pbid = 25323 | Possible Denial of Service Activity n°2
--> Comment: Take about 10 seconds first time execution (then almost instantly)

Test	Parameters	Result
1	eventtype='connection' without count	200 items ✓
2	eventtype='connection' with count=100	0 item✖
3	eventtype='notice' with count=800	0 items ✖
4	no eventtype with count=100	0 items✖

Test: pbid = 28384 | SMB Drive Write

Test	Parameters	Result
1	eventtype='connection' without count	1 items ✓
2	eventtype='connection' with count=100	0 item✖
3	eventtype='notice' with count=800	10 items ✓
4	no eventtype with count=100	0 items✖

Test: pbid = 27440 | SMB Session Brute Force (Non-Admin)

Test	Parameters	Result
1	eventtype='connection' without count	200 items ✓
2	eventtype='connection' with count=100	0 item✖
3	eventtype='notice' with count=800	0 items ✖
4	no eventtype with count=100	0 items✖

Here is below the full script used (the one that you provide didn't work due to \"TEST Backslash char)
ERROR GOT with your script:

  (\"TEST 2: connection with count=100", {"pbid": pbid, "eventtype": "connection", "count": 100}),
      ^
SyntaxError: unexpected character after line continuation character

from darktrace import DarktraceClient
import urllib3

urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

client = DarktraceClient(
    host="https://your-darktrace-instance",
    public_token="YOUR_PUBLIC_TOKEN",
    private_token="YOUR_PRIVATE_TOKEN",
    debug=True
)

#tested with the following pbid: 27439, 28294, 25323, 28384, 27440

#pbid = 27439  # Anomalous NTLM Brute Force
#pbid = 28294 # Possible Denial of Service Activity n°1
#pbid = 25323 # Possible Denial of Service Activity n°2
#pbid = 28384 # SMB Drive Write // Correct manual verification
pbid = 27440  # SMB Session Brute Force (Non-Admin)

for name, kwargs in [
    ("TEST 1: connection without count", {"pbid": pbid, "eventtype": "connection"}),
    ("TEST 2: connection with count=100", {"pbid": pbid, "eventtype": "connection", "count": 100}),
    ("TEST 3: notice with count=800", {"pbid": pbid, "eventtype": "notice", "count": 800}),
    ("TEST 4: no eventtype with count=100", {"pbid": pbid, "count": 100}),
]:
    print(f"\n{name}")
    result = client.details.get(**kwargs)
    print(f"  Type: {type(result).__name__}")
    print(f"  len(): {len(result)}")

from darktrace import __version__
print(f"\nSDK version: {__version__}")
status = client.status.get()
print(f"Darktrace version: {status.get('version', 'unknown')}")

By the way i've also upgrade the SDK version to 0.8.55 and got the same result
I've tested the result on the API through the Browser, i got the same results than the ones retrieved by API

[LegendEvent]

Root Cause: User Token Permission Restrictions

Thank you for the detailed testing. The official Darktrace API Guide v6.1 states:

"The API endpoints accessible by user tokens are restricted to those the user can access in the Threat Visualizer user interface."

"The global API token generated on the System Config page is not subject to these restrictions."

Minimum Required Permissions for /details

"Unrestricted Devices and any of: Visualizer/Platform Accounts Console"

Your user account likely has partial access to `/details`, but not the full permissions required for the `count` parameter.

Solution

Generate a Global API Token and test again:

1. Log in with an admin account
2. Navigate to System Config → Settings → API Token
3. Click New to generate a Global API Token pair
4. Test with the debug script

The Global API Token bypasses user permission restrictions.

---

Reference: Working Setup with Global API Token

Environment:

• SDK: 0.8.55
• Darktrace: 6.3.18
• Token type: Global API Token (System Config > API Token)

Timing Results (4 runs per pbid):

PBID	Test	Run 1	Run 2	Run 3	Run 4	Items
70252	connection WITHOUT count	0.187s	0.190s	0.187s	0.306s	22
70252	connection WITH count=100	0.192s	0.185s	0.198s	0.193s	22 ✓
70252	notice WITH count=800	0.261s	0.228s	0.226s	0.238s	3
70252	NO eventtype WITH count=100	0.206s	0.245s	0.189s	0.196s	22 ✓
70245	connection WITHOUT count	0.237s	0.182s	0.200s	0.200s	21
70245	connection WITH count=100	0.188s	0.255s	0.200s	0.199s	21 ✓
70245	notice WITH count=800	0.226s	0.238s	0.356s	0.338s	2
70245	NO eventtype WITH count=100	0.187s	0.201s	0.192s	0.193s	21 ✓

Key observations:

• All requests complete in ~0.2-0.3s (no 10-second delays)
• `count` parameter works correctly with all eventtypes
• No significant difference between first run and subsequent runs

---

Please provide your timing data

Run this script and share the output:

#!/usr/bin/env python3
import os, sys, time
from darktrace import DarktraceClient

DEFAULT_PBIDS = [27439, 28294, 25323, 28384, 27440]

host = os.environ.get("DARKTRACE_HOST") or input("Host: ")
public = os.environ.get("DARKTRACE_PUBLIC_TOKEN") or input("Public token: ")
private = os.environ.get("DARKTRACE_PRIVATE_TOKEN") or input("Private token: ")
client = DarktraceClient(host=host, public_token=public, private_token=private)

pbids = DEFAULT_PBIDS
for pbid in pbids:
    print(f"\n=== PBID {pbid} ===")
    for name, kwargs in [
        ("connection WITHOUT count", {"pbid": pbid, "eventtype": "connection"}),
        ("connection WITH count=100", {"pbid": pbid, "eventtype": "connection", "count": 100}),
        ("notice WITH count=800", {"pbid": pbid, "eventtype": "notice", "count": 800}),
        ("NO eventtype WITH count=100", {"pbid": pbid, "count": 100}),
    ]:
        t0 = time.perf_counter()
        r = client.details.get(**kwargs)
        dt = time.perf_counter() - t0
        n = len(r) if isinstance(r, list) else sum(len(v) for v in r.values() if isinstance(v, list))
        print(f"  {name}: {dt:.2f}s, {n} items")

print(f"\nSDK: {__import__('darktrace').__version__}")
print(f"Darktrace: {client.status.get().get('version', 'unknown')}")

This will help confirm if the issue is resolved with a Global API Token.

[Nicolas-Pellletier]

Hello @LegendEvent ,

Thanks for your reply, i really appreciate the detail of your answer and your prompt response.
I've tried with both Global API token and User Token. The User token is a user with all permission set. (Unrestricted one)
I've also contacted Darktrace on this issue i'm facing. And they were able to reproduce the error on their side. They didn't use your tool. I'm also able to reproduce the error through my browser.
Maybe this issue happend to only my Darktrace instance. I'll keep you updated regarding this.

Regards

[LegendEvent]

Thank you for the update and for contacting Darktrace support directly.

Since:

• You tested with both token types (same issue)
• Darktrace support reproduced it without the SDK
• It's reproducible through the browser

This confirms it's a Darktrace backend issue, not an SDK bug.

I've removed the "bug" label. Please keep us posted on Darktrace's response - if they identify an API change or workaround, we can implement it in the SDK.

Thank you for your thorough testing and collaboration on this!