Reports

Usage reports

List organization reports

get

Authorizations

Path parameters

organizationIdstring · uuidRequired

The ID of the organization.

Query parameters

limitinteger · min: 1 · max: 100Optional

Limits the number of results to return

Default: 10

pageTokenstring · max: 8000Optional

Pagination token that keeps of track of the current position in the list

reversebooleanOptional

Order in which to retrieve the results

Default: false

Responses

200

application/json

get

GET /organizations/{organizationId}/reports HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

200

{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "from": "2025-09-15",
      "productName": "text",
      "to": "2025-09-15",
      "createdAt": "2025-09-15T15:57:31.767Z",
      "productId": "123e4567-e89b-12d3-a456-426614174000",
      "createdBy": "123e4567-e89b-12d3-a456-426614174000",
      "organizationId": "123e4567-e89b-12d3-a456-426614174000",
      "rawKey": "text",
      "enrichedKey": "text",
      "status": "pending",
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "reportType": "itemised"
    }
  ]
}

curl -X GET "https://api.bird.com/organizations/{organizationId}/reports" \
 -H "Content-Type: application/json" \
 -H "Authorization: AccessKey abcd"

{
  "results": [
    {
      "id": "b657e211-a13c-58f0-85cb-508f622a502a",
      "reportType": "itemised",
      "organizationId": "organizationId",
      "productId": "productId",
      "productName": "cd03ae6e-90f8-4aa0-aba4-c1190acaf2bd",
      "createdBy": "createdBy",
      "rawKey": "rawKey.csv",
      "enrichedKey": "enrichedKey.csv.zip",
      "from": "2025-08-01",
      "to": "2025-08-31",
      "status": "complete",
      "createdAt": "2025-09-15T10:53:09.156Z",
      "metadata": null
    }
  ]
}

Create itemised report for organization and product

post

Authorizations

Path parameters

organizationIdstring · uuidRequired

The ID of the organization.

Body

request to generate an itemised report

productIdstring · uuidRequired

ID of the product to generate report for

fromstring · dateRequired

Start date of the report period

tostring · dateRequired

End date of the report period

Responses

201

Created

application/json

404

The requested resource does not exist

application/json

422

The requested resource does not exist

application/json

post

POST /organizations/{organizationId}/reports HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 90

{
  "productId": "123e4567-e89b-12d3-a456-426614174000",
  "from": "2025-09-15",
  "to": "2025-09-15"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "from": "2025-09-15",
  "productName": "text",
  "to": "2025-09-15",
  "createdAt": "2025-09-15T15:57:31.767Z",
  "productId": "123e4567-e89b-12d3-a456-426614174000",
  "createdBy": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "rawKey": "text",
  "enrichedKey": "text",
  "status": "pending",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "reportType": "itemised"
}

curl -X POST "https://api.bird.com/organizations/{organizationId}/reports" \
 -H "Content-Type: application/json" \
 -H "Authorization: AccessKey abcd" \
 -d '{"productId": "9c31bfb6-d792-4a88-a0b9-904230230de5", "from": "2025-08-01", "to": "2025-08-10"}'

{
  "id": "150cb1d0-31f6-564b-af7f-b158b1c4b864",
  "reportType": "itemised",
  "organizationId": "organizationId",
  "productId": "9c31bfb6-d792-4a88-a0b9-904230230de5",
  "productName": "Alphanumeric",
  "createdBy": "da0a76a1-d0c7-4128-96d1-6951e6112d23",
  "rawKey": "feafd337-5d7e-42a5-a020-a4cbec8a2252/raw/feafd337-5d7e-42a5-a020-a4cbec8a2252_9c31bfb6-d792-4a88-a0b9-904230230de5_2025-08-01_2025-08-100.csv",
  "enrichedKey": "",
  "from": "2025-08-01",
  "to": "2025-08-10",
  "status": "pending",
  "createdAt": "2025-09-15T11:44:10.011Z",
  "metadata": null
}

ProductName

ProductId

abd21841-400c-4d1a-8322-51929abe668c

alphanumeric

9c31bfb6-d792-4a88-a0b9-904230230de5

chat

a59a938c-ada8-4100-8834-c541798fcb48

contact-lookup

49f682ae-6e30-440e-b86e-7d9171d0b35a

contacts

82fff5bd-e147-4fcc-a8c9-760adfbea58b

2a1b4126-2a2d-4dcc-bac1-9ec7fa632394

facebook

9728f45c-2686-4f20-b721-3ba98d33f5c0

flows

b815c4f7-a3be-465d-a5e6-2e3c05a10c23

inbox

6f44ba37-30b7-40d8-b8b0-c613d6b06ef4

instagram

2c384c4d-bc72-4b5e-8ef7-2c020a6538d7

journeys

67f75d99-9b64-46ba-958b-ad2a7629d850

line

1b240f93-cf07-4edf-9866-571d008d603f

mms

e88a8f43-d2ff-4ae6-9bb2-f4d00ff4b1e1

mms10dlc

a7d6fca8-96a6-4b2a-8993-d537a5ffeb7d

numbers

cd03ae6e-90f8-4aa0-aba4-c1190acaf2bd

shortcode

9e110353-70fb-4a89-bbbc-57b785c36b20

sms

ba676254-3771-448e-b499-fddab7182ccb

sms10dlc

856bdb66-2c5a-4c02-a332-27dadffbc502

cd570663-b355-4f38-8766-1d25ea106bbe

voice

70520167-460d-41ac-bf99-04eb26517814

0177585d-27cf-45f3-b43f-fdd8cb2dcce6

Create different report for organization and product by type

post

Authorizations

Path parameters

organizationIdstring · uuidRequired

The ID of the organization.

reportTypestring · enumRequired

Filter organization bundles by status

Possible values:

Body

one ofOptional

Responses

201

Created

application/json

404

The requested resource does not exist

application/json

422

The requested resource does not exist

application/json

post

POST /organizations/{organizationId}/reports/{reportType} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 90

{
  "productId": "123e4567-e89b-12d3-a456-426614174000",
  "from": "2025-09-15",
  "to": "2025-09-15"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "from": "2025-09-15",
  "productName": "text",
  "to": "2025-09-15",
  "createdAt": "2025-09-15T15:57:31.767Z",
  "productId": "123e4567-e89b-12d3-a456-426614174000",
  "createdBy": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "rawKey": "text",
  "enrichedKey": "text",
  "status": "pending",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "reportType": "itemised"
}

curl -X POST "https://api.bird.com/organizations/{organizationId}/reports/aggregated" \
 -H "Content-Type: application/json" \
 -H "Authorization: AccessKey abcd" \
 -d '{"productId": "ba676254-3771-448e-b499-fddab7182ccb", "from": "2025-08-01", "to": "2025-08-31", "periodAggregation": "day"}'

{
  "id": "5338f834-ffbd-557c-bbed-c33f1c785d71",
  "reportType": "aggregated",
  "organizationId": "organizationId",
  "productId": "ba676254-3771-448e-b499-fddab7182ccb",
  "productName": "SMS Channel",
  "createdBy": "da0a76a1-d0c7-4128-96d1-6951e6112d23",
  "rawKey": "acb8572c-5432-4147-8c4b-aedb238702d4/raw/agg_prd_usg_acb8572c-5432-4147-8c4b-aedb238702d4_ba676254-3771-448e-b499-fddab7182ccb__2025-08-01_2025-08-310.csv",
  "enrichedKey": "",
  "from": "2025-08-01",
  "to": "2025-08-31",
  "status": "pending",
  "createdAt": "2025-09-15T12:56:57.44Z",
  "metadata": {
    "periodAggregation": "day",
    "units": null
  }
}

Download report csv file

get

Authorizations

Path parameters

organizationIdstring · uuidRequired

The ID of the organization.

reportIdstring · uuidRequired

The ID of a Report.

Responses

200

Responsestring · binary

400

The requested resource does not exist

application/json

404

The requested resource does not exist

application/json

get

GET /organizations/{organizationId}/reports/{reportId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

binary

curl -X GET "https://api.bird.com/organizations/organizationId/reports/61e9b0a8-b69d-5844-8722-0f9e844af813" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-o downloadreport.zip

Last updated 2 hours ago

Was this helpful?