Skip to content
nsin nsin nsin Docs

Run a custom query over your request logs

POST
/analytics/query
 
curl --request POST \
  --url https://api.nsin.ir/analytics/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "sql": "SELECT toStartOfHour(event_time) AS h, count() AS c FROM requests WHERE status >= 500 GROUP BY h ORDER BY h" }'

Runs a read-only SQL SELECT against the requests table — your raw request log — for analyses the dedicated endpoints do not cover.

Scoping is enforced by the database engine, not by your query: a filter restricting rows to the domains this key can access is appended to every read of requests. You cannot read another account’s traffic, however the query is written.

Restrictions:

  • A single statement only, starting with SELECT or WITH.
  • Only the requests table may be read. Common table expressions you define yourself are fine; other tables and any db.table reference are rejected.
  • Writes, DDL and settings changes are rejected.
  • Execution is capped at 30 seconds and 10 000 returned rows — truncated tells you when the cap was hit.

Useful requests columns: event_time, domain_id, hostname, method, uri, status, bytesIn, bytesOut, duration (ms), remoteAddr, country, asn, asnOrg, userAgent, cacheStatus, reqStatus, isWS, protocol, referer, originStatus, originAddr, error.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type application/json
object
sql
required

The query to run.

string

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Query result.

Media type application/json
object
columns

Column names, in result order.

Array<string>
rows

One entry per row, keyed by column name.

Array<object>
object
key
additional properties
any
row_count
integer
truncated

True when the 10 000-row cap was reached and results were cut short.

boolean
Example generated
{
  "columns": [
    "example"
  ],
  "rows": [
    {}
  ],
  "row_count": 1,
  "truncated": true
}

400

Section titled “400 ”

The query was rejected by validation, or the database refused it. detail carries the underlying message when the engine rejected it.

Media type application/json
object
error
string
detail
string
Examples
Example disallowedTable 
{
  "error": "querying \"system.parts\" is not allowed; only the 'requests' table may be read"
}

401

Section titled “401 ”

Missing, malformed, revoked or expired API key — or the owning account is inactive.

Media type application/json

The single error shape used by every endpoint.

object
error
required

Human-readable description of what went wrong.

string
Examples
Example invalidKey 
{
  "error": "invalid API key"
}

403

Section titled “403 ”

Read-only key, or the account has no domains whose logs could be queried.

Media type application/json

The single error shape used by every endpoint.

object
error
required

Human-readable description of what went wrong.

string
Example 
{
  "error": "read-only API key"
}

429

Section titled “429 ”

The key exceeded its request budget (300 requests per minute by default).

Media type application/json

The single error shape used by every endpoint.

object
error
required

Human-readable description of what went wrong.

string
Examples
Example limited 
{
  "error": "rate limit exceeded"
}

503

Section titled “503 ”

The analytics backend is temporarily unreachable. Retry; no data is lost.

Media type application/json

The single error shape used by every endpoint.

object
error
required

Human-readable description of what went wrong.

string
Examples
Example unavailable 
{
  "error": "analytics unavailable"
}